praxis_policy_core/

plugin.rs

// SPDX-License-Identifier: Apache-2.0
// Copyright (c) 2026 Praxis Contributors

// Plugin trait and supporting types.
//
// Defines the core Plugin trait that all plugin implementations satisfy —
// native Rust, WASM hosts, and dlopen'd shared
// libraries. Also defines PluginConfig (YAML-declared plugin settings),
// PluginMode (5-phase execution modes), and OnError (failure behavior).
//
// The Plugin trait handles lifecycle only (initialize, shutdown, config).
// Hook-specific logic is defined by handler traits generated by the
// define_hook! macro (see hooks/macros.rs). A plugin implements Plugin
// for lifecycle + one or more handler traits for the hooks it handles.
//
// The engine wraps each plugin in a PluginRef with an authoritative
// config from the config loader — the plugin's own config() is for
// the plugin's reading only, never used by the executor for scheduling.

use std::collections::HashSet;
use std::fmt;
use std::sync::Arc;

use async_trait::async_trait;
use serde::{Deserialize, Serialize};

use crate::error::PluginError;
use crate::host::InitExtensions;

/// Core plugin interface — lifecycle management only.
///
/// Every plugin in the PPE framework — regardless of language or
/// deployment model — implements this trait. It covers lifecycle
/// (initialize, shutdown) and identity (config). Hook-specific logic
/// is defined separately by handler traits generated by `define_hook!`.
///
/// # Lifecycle
///
/// 1. `initialize()` — called once after loading, before any hooks fire.
/// 2. Hook handlers — called on each hook invocation (defined by handler traits).
/// 3. `shutdown()` — called once during graceful teardown.
///
/// # Hook Handlers
///
/// A plugin implements one or more handler traits alongside Plugin:
///
/// ```rust,ignore
/// impl Plugin for MyPlugin {
///     fn config(&self) -> &PluginConfig { &self.config }
///     async fn initialize(&self) -> Result<(), Box<PluginError>> { Ok(()) }
///     async fn shutdown(&self) -> Result<(), Box<PluginError>> { Ok(()) }
/// }
///
/// impl CmfHookHandler for MyPlugin {
///     fn cmf_hook(&self, payload: MessagePayload, ext: &Extensions, ctx: &PluginContext) -> PluginResult<MessagePayload> {
///         PluginResult::allow()
///     }
/// }
/// ```
///
/// # Trust Model
///
/// The engine wraps each plugin in a `PluginRef` with an authoritative
/// config from the config loader. The executor reads scheduling decisions
/// (mode, priority, hooks, capabilities) from the `PluginRef` — never
/// from `plugin.config()`. The plugin's own `config()` is available for
/// the plugin's reading during hook execution.
///
/// # Implementors
///
/// - Native Rust plugins (implement directly)
/// - Out-of-process host bridges (WASM, dlopen'd native), which live
///   outside this repository
#[async_trait]
pub trait Plugin: Send + Sync {
    /// Returns the plugin's configuration.
    ///
    /// Available for the plugin's own reading during hook execution.
    /// The engine/executor never reads this — they use the authoritative
    /// config from `PluginRef.trusted_config()`.
    fn config(&self) -> &PluginConfig;

    /// One-time initialization after loading.
    ///
    /// Called before any hook invocations. Use this to establish
    /// connections, load resources, or validate configuration.
    /// Default implementation does nothing.
    ///
    /// Implement this when initialization needs nothing from the host.
    /// A plugin that must reach a host service — an outbound HTTP call
    /// to fetch signing keys, say — implements
    /// [`initialize_with`](Self::initialize_with) instead.
    async fn initialize(&self) -> Result<(), Box<PluginError>> {
        Ok(())
    }

    /// One-time initialization, with the host services this plugin is
    /// permitted to borrow.
    ///
    /// This is the method the engine calls. The default forwards to
    /// [`initialize`](Self::initialize), so a plugin needing no host
    /// services implements that one and never names [`InitExtensions`].
    ///
    /// `ext` carries only what this plugin's capabilities allow, and
    /// only for the duration of the call. Borrow per use and store
    /// nothing: the grants are re-evaluated on every request, so a
    /// handle stashed here would outlive a capability an operator later
    /// revoked. At request time the same services arrive through
    /// `Extensions`, which implements the same
    /// [`HostServices`](crate::host::HostServices) trait.
    ///
    /// # Implementing
    ///
    /// Override **exactly one** of this and [`initialize`](Self::initialize).
    /// The default body here is what calls `initialize`, so overriding
    /// this one replaces it — if you implement both, call
    /// `self.initialize().await` yourself or its work silently never
    /// runs.
    ///
    /// # Errors
    ///
    /// Returns `PluginError` when initialization fails. Returning an
    /// error aborts engine startup and shuts down the plugins that
    /// already initialized, so the engine never comes up half-started.
    async fn initialize_with(&self, ext: &InitExtensions) -> Result<(), Box<PluginError>> {
        let _ = ext;
        self.initialize().await
    }

    /// Graceful shutdown.
    ///
    /// Called once during teardown. Use this to flush buffers, close
    /// connections, or release resources.
    /// Default implementation does nothing.
    async fn shutdown(&self) -> Result<(), Box<PluginError>> {
        Ok(())
    }

    /// If this plugin is also an audit sink, return it as one so the engine
    /// attaches it to the executor's verdict emit when the plugin is
    /// registered, config-driven registration included.
    ///
    /// A sink sees the verdict and every plugin's action but returns nothing,
    /// so it cannot influence the outcome it records. Default: not a sink.
    fn as_audit_handler(self: Arc<Self>) -> Option<Arc<dyn crate::audit::AuditHandler>> {
        None
    }
}

/// Declared plugin configuration from the unified YAML config.
///
/// Controls how the framework loads, schedules, and gates the plugin.
/// Corresponds to a single entry in the `plugins:` list in config YAML.
///
/// The engine holds the authoritative copy in `PluginRef.trusted_config`.
/// The plugin receives its own copy for reading via `Plugin::config()`.
///
/// # Examples
///
/// ```yaml
/// plugins:
///   - name: apl-policy
///     kind: builtin
///     # Validated at load; see the `hooks` field for the names that
///     # dispatch and what a host with its own hooks has to do first.
///     hooks: [cmf.tool_pre_invoke, cmf.tool_post_invoke]
///     mode: sequential
///     priority: 10
///     on_error: fail
///     capabilities: [read_security, append_labels]
///     config:
///       policy_file: apl/demo/hr_policy.yaml
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PluginConfig {
    /// Unique plugin name.
    pub name: String,

    /// Plugin kind — determines how the framework loads it.
    ///
    /// - `"builtin"` — compiled into the runtime
    /// - `"native://path/to/lib.so"` — dlopen'd shared library
    /// - `"wasm://path/to/plugin.wasm"` — wasmtime sandbox
    /// - `"external"` — MCP/gRPC/Unix socket transport
    pub kind: String,

    /// Human-readable description.
    #[serde(default)]
    pub description: Option<String>,

    /// Plugin author or team.
    #[serde(default)]
    pub author: Option<String>,

    /// Semantic version string.
    #[serde(default)]
    pub version: Option<String>,

    /// Hook names this plugin handles.
    ///
    /// Validated at config load: a name no hook answers to refuses the
    /// config. What the check guarantees is that the name is one PPE
    /// dispatches or the host has described, not that this plugin handles
    /// it: a factory registers its handlers under names of its own
    /// choosing, and only a factory that reads this field registers under
    /// what it lists. The names
    /// PPE dispatches are the constants in
    /// [`cmf::constants`][crate::cmf::constants] plus
    /// [`identity::HOOK_IDENTITY_RESOLVE`][crate::identity::HOOK_IDENTITY_RESOLVE],
    /// [`delegation::HOOK_TOKEN_DELEGATE`][crate::delegation::HOOK_TOKEN_DELEGATE],
    /// and [`elicitation::HOOK_ELICIT`][crate::elicitation::HOOK_ELICIT].
    ///
    /// A host with its own hooks describes them through
    /// [`register_hook_metadata`][crate::hooks::register_hook_metadata]
    /// **before** loading config that names them. Registering afterwards is
    /// too late: the load has already refused.
    ///
    /// An empty list is not a typo, and plugins that register their handler
    /// in Rust need nothing here.
    #[serde(default)]
    pub hooks: Vec<String>,

    /// Execution mode — determines scheduling behavior and authority.
    #[serde(default)]
    pub mode: PluginMode,

    /// Execution priority, under `dispatch: hooks`. Lower numbers execute first
    /// within each mode.
    ///
    /// **Hook mode only.** Declaring it under `dispatch: policy` is a load error:
    /// it orders the entries one hook holds, and policy dispatch never runs more
    /// than one at a time. Effects run in document order and a `run(name)` step
    /// invokes the one plugin it names, so nothing would consult the priority.
    #[serde(default = "default_priority")]
    pub priority: i32,

    /// Error handling behavior when the plugin fails.
    #[serde(default)]
    pub on_error: OnError,

    /// Declared capabilities for extension visibility gating.
    ///
    /// Controls which extensions the plugin can see and modify.
    /// Extensions not covered by declared capabilities appear as
    /// `None` in the filtered view.
    #[serde(default)]
    pub capabilities: HashSet<String>,

    /// Tags for categorization and searchability.
    #[serde(default)]
    pub tags: Vec<String>,

    /// How a plugin narrows its own scope, under `dispatch: hooks`.
    ///
    /// Each condition narrows the plugin's scope by server, tenant,
    /// tool name, prompt name, etc. If any condition in the list
    /// matches, the plugin runs. If the list is empty (default),
    /// the plugin runs unconditionally.
    ///
    /// **Hook mode only.** Declaring it under `dispatch: policy` is a load
    /// error: a policy decides dispatch there, so nothing would consult the
    /// condition. `priority:` is restricted the same way, for the same reason.
    #[serde(default)]
    pub conditions: Vec<PluginCondition>,

    /// Plugin-specific configuration (opaque to the framework).
    #[serde(default)]
    pub config: Option<serde_json::Value>,
}

impl PluginConfig {
    /// Whether this plugin's `conditions` allow it to fire for the given
    /// request `Extensions`. Used in hook mode (`dispatch: hooks`)
    /// to filter which plugins run per request.
    ///
    /// Semantics:
    /// - Empty `conditions` Vec → fire always (no restriction).
    /// - Non-empty → fire if ANY condition matches (OR across the list,
    ///   AND within each individual condition).
    ///
    /// Field-source mapping (see project memory `project_conditions_field_mapping`):
    /// - `server_ids` ← `extensions.mcp.{tool|resource|prompt}.server_id`
    /// - `tenant_ids` ← `extensions.security.subject.claims["tenant"]`
    /// - `tools|prompts|resources` ← `extensions.meta.entity_name` (when matching `entity_type`)
    /// - `agents` ← `extensions.agent.agent_id`
    /// - `user_patterns` ← `extensions.security.subject.id` (glob match)
    /// - `content_types` ← `extensions.mcp.resource.mime_type`
    pub fn passes_conditions(&self, extensions: &crate::hooks::payload::Extensions) -> bool {
        if self.conditions.is_empty() {
            return true;
        }

        // Source values once from the extensions tree.
        let server_id = extensions.mcp.as_ref().and_then(|m| {
            m.tool
                .as_ref()
                .and_then(|t| t.server_id.as_deref())
                .or_else(|| m.resource.as_ref().and_then(|r| r.server_id.as_deref()))
                .or_else(|| m.prompt.as_ref().and_then(|p| p.server_id.as_deref()))
        });
        // `claim_str` renders a scalar claim, so a numeric tenant id still
        // matches the text an operator configured. A structured claim names
        // no single tenant and yields `None`, which `check_set` treats as
        // no-match.
        let tenant_claim = extensions
            .security
            .as_ref()
            .and_then(|s| s.subject.as_ref())
            .and_then(|sub| sub.claim_str("tenant"));
        let tenant_id = tenant_claim.as_deref();
        let entity_name = extensions
            .meta
            .as_ref()
            .and_then(|m| m.entity_name.as_deref());
        let entity_type = extensions
            .meta
            .as_ref()
            .and_then(|m| m.entity_type.as_deref());
        let (tool, prompt, resource) = match entity_type {
            Some("tool") => (entity_name, None, None),
            Some("prompt") => (None, entity_name, None),
            Some("resource") => (None, None, entity_name),
            _ => (None, None, None),
        };
        let agent = extensions
            .agent
            .as_ref()
            .and_then(|a| a.agent_id.as_deref());
        let user = extensions
            .security
            .as_ref()
            .and_then(|s| s.subject.as_ref())
            .and_then(|sub| sub.id.as_deref());
        let content_type = extensions
            .mcp
            .as_ref()
            .and_then(|m| m.resource.as_ref())
            .and_then(|r| r.mime_type.as_deref());

        let ctx = MatchContext {
            server_id,
            tenant_id,
            tool,
            prompt,
            resource,
            agent,
            user,
            content_type,
        };
        self.conditions.iter().any(|c| c.matches(&ctx))
    }
}

fn default_priority() -> i32 {
    100
}

/// Condition for when a plugin should execute.
///
/// Narrows plugin scope to specific servers, tenants, tools, prompts,
/// resources, or agents. All fields are optional — only specified
/// fields participate in matching. Within a field, any match suffices
/// (OR semantics). Across fields, all must match (AND semantics).
///
/// Hook mode's scoping mechanism. Under `dispatch: policy` a policy step's
/// `run(name)` scopes the plugin instead, and a `conditions:` block there is a
/// load error rather than an ignored one.
///
///
/// # Examples
///
/// ```
/// use praxis_policy_core::plugin::PluginCondition;
///
/// // Only run for specific tools on specific servers
/// let cond = PluginCondition {
///     server_ids: Some(vec!["server-1".into(), "server-2".into()].into_iter().collect()),
///     tools: Some(vec!["get_compensation".into()].into_iter().collect()),
///     ..Default::default()
/// };
/// assert!(cond.server_ids.as_ref().unwrap().contains("server-1"));
/// assert!(cond.tools.as_ref().unwrap().contains("get_compensation"));
/// ```
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PluginCondition {
    /// Set of server IDs — plugin runs only on these servers.
    #[serde(default)]
    pub server_ids: Option<HashSet<String>>,

    /// Set of tenant IDs — plugin runs only for these tenants.
    #[serde(default)]
    pub tenant_ids: Option<HashSet<String>>,

    /// Set of tool names — plugin runs only for these tools.
    #[serde(default)]
    pub tools: Option<HashSet<String>>,

    /// Set of prompt names — plugin runs only for these prompts.
    #[serde(default)]
    pub prompts: Option<HashSet<String>>,

    /// Set of resource identifiers — plugin runs only for these resources.
    #[serde(default)]
    pub resources: Option<HashSet<String>>,

    /// Set of agent identifiers — plugin runs only for these agents.
    #[serde(default)]
    pub agents: Option<HashSet<String>>,

    /// User patterns (glob or regex) — plugin runs only for matching users.
    #[serde(default)]
    pub user_patterns: Option<Vec<String>>,

    /// Content types — plugin runs only for these content types.
    #[serde(default)]
    pub content_types: Option<Vec<String>>,
}

/// Bundle of optional context values used to evaluate a `PluginCondition`.
///
/// Each field corresponds to one of the condition's gates. `None` means
/// "no value sourced from the extensions tree"; the condition then
/// rejects when the corresponding `Some(set)` is set on the condition
/// (i.e., the gate was specified but couldn't be evaluated).
///
/// Replaces an 8-arg `matches(...)` call where every arg was
/// `Option<&str>` and could be misordered silently.
#[derive(Debug, Default, Clone, Copy)]
pub struct MatchContext<'a> {
    /// The server the request is bound for.
    pub server_id: Option<&'a str>,
    /// The tenant the request belongs to.
    pub tenant_id: Option<&'a str>,
    /// The tool being invoked.
    pub tool: Option<&'a str>,
    /// The prompt being rendered.
    pub prompt: Option<&'a str>,
    /// The resource being fetched.
    pub resource: Option<&'a str>,
    /// The calling agent.
    pub agent: Option<&'a str>,
    /// The acting user.
    pub user: Option<&'a str>,
    /// The content type in play.
    pub content_type: Option<&'a str>,
}

impl PluginCondition {
    /// Whether this condition matches the given context.
    ///
    /// A field that is `None` is treated as "any" (no restriction).
    /// A `Some(set)` field matches if the given value is in the set
    /// (exact match for ID-shaped fields; glob match via `wildmatch`
    /// for `user_patterns`).
    /// All specified fields must match — AND semantics within one condition.
    pub fn matches(&self, ctx: &MatchContext<'_>) -> bool {
        let MatchContext {
            server_id,
            tenant_id,
            tool,
            prompt,
            resource,
            agent,
            user,
            content_type,
        } = *ctx;
        let check_set = |field: &Option<HashSet<String>>, value: Option<&str>| -> bool {
            match field {
                None => true, // not specified — matches anything
                Some(set) => match value {
                    Some(v) => set.contains(v),
                    None => false, // field required but no value provided
                },
            }
        };

        // user_patterns: list of globs. Match if any pattern matches the user.
        let check_patterns = |field: &Option<Vec<String>>, value: Option<&str>| -> bool {
            match field {
                None => true,
                Some(patterns) => match value {
                    Some(v) => patterns
                        .iter()
                        .any(|p| wildmatch::WildMatch::new(p).matches(v)),
                    None => false,
                },
            }
        };

        // content_types: list of exact strings.
        let check_list = |field: &Option<Vec<String>>, value: Option<&str>| -> bool {
            match field {
                None => true,
                Some(list) => match value {
                    Some(v) => list.iter().any(|s| s == v),
                    None => false,
                },
            }
        };

        check_set(&self.server_ids, server_id)
            && check_set(&self.tenant_ids, tenant_id)
            && check_set(&self.tools, tool)
            && check_set(&self.prompts, prompt)
            && check_set(&self.resources, resource)
            && check_set(&self.agents, agent)
            && check_patterns(&self.user_patterns, user)
            && check_list(&self.content_types, content_type)
    }
}

/// Execution mode — determines a plugin's scheduling behavior and authority.
///
/// The 5-phase model defines both what a plugin *can do* (block, modify)
/// and *how it runs* (serial, parallel, background). Scheduling is derived
/// from mode; plugin authors don't control it directly.
///
/// # Execution Order
///
/// ```text
/// SEQUENTIAL → TRANSFORM → AUDIT → CONCURRENT → FIRE_AND_FORGET
/// ```
///
/// # Mode Capabilities
///
/// | Mode           | Can Block? | Can Modify? | Execution       |
/// |----------------|------------|-------------|-----------------|
/// | Sequential     | Yes        | Yes         | Serial, chained |
/// | Transform      | No         | Yes         | Serial, chained |
/// | Audit          | No         | No          | Serial          |
/// | Concurrent     | Yes        | No          | Parallel        |
/// | FireAndForget  | No         | No          | Background      |
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum PluginMode {
    /// Policy enforcement + transformation. Serial, chained. Can block and modify.
    #[default]
    Sequential,

    /// Data shaping (PII redaction, normalization). Serial, chained. Can modify, cannot block.
    Transform,

    /// Observation and logging. Serial, read-only. Cannot block or modify.
    Audit,

    /// Independent policy gates. Parallel, fail-fast. Can block, cannot modify.
    Concurrent,

    /// Telemetry and async side effects. Background tasks. Cannot block or modify.
    FireAndForget,

    /// Plugin is disabled — skipped during execution.
    Disabled,
}

impl PluginMode {
    /// Whether this mode allows the plugin to block the pipeline.
    pub fn can_block(&self) -> bool {
        match self {
            Self::Sequential | Self::Concurrent => true,
            Self::Transform | Self::Audit | Self::FireAndForget | Self::Disabled => false,
        }
    }

    /// Whether this mode allows the plugin to modify the payload.
    pub fn can_modify(&self) -> bool {
        match self {
            Self::Sequential | Self::Transform => true,
            Self::Audit | Self::Concurrent | Self::FireAndForget | Self::Disabled => false,
        }
    }

    /// Whether the framework waits for this plugin to complete.
    pub fn is_awaited(&self) -> bool {
        match self {
            Self::FireAndForget | Self::Disabled => false,
            Self::Sequential | Self::Transform | Self::Audit | Self::Concurrent => true,
        }
    }

    /// Whether the executor dispatches this mode as a phase.
    ///
    /// `Disabled` is skipped. The match is exhaustive so a new variant is a
    /// compile error until the catalog in `docs/dev/safety-invariants.md` gains a
    /// cell for it.
    pub fn is_dispatch_phase(&self) -> bool {
        match self {
            Self::Disabled => false,
            Self::Sequential
            | Self::Transform
            | Self::Audit
            | Self::Concurrent
            | Self::FireAndForget => true,
        }
    }

    /// Whether a plugin in this mode may perform an irreversible external
    /// effect (a token mint, an approval grant).
    ///
    /// Only the serial phases qualify. A concurrent branch is cancelled when
    /// another branch short-circuits the phase, an audit-phase plugin is
    /// read-only by contract, and fire-and-forget runs after the verdict is
    /// already returned. In each of those an external act would happen for
    /// work the pipeline discarded, and an external act cannot be discarded.
    pub fn permits_effects(&self) -> bool {
        matches!(self, Self::Sequential | Self::Transform)
    }
}

impl fmt::Display for PluginMode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Sequential => write!(f, "sequential"),
            Self::Transform => write!(f, "transform"),
            Self::Audit => write!(f, "audit"),
            Self::Concurrent => write!(f, "concurrent"),
            Self::FireAndForget => write!(f, "fire_and_forget"),
            Self::Disabled => write!(f, "disabled"),
        }
    }
}

/// Error handling behavior when a plugin fails.
///
/// Independent of [`PluginMode`] — any mode can use any error behavior.
/// Controls whether plugin failures halt the pipeline, are logged and
/// skipped, or cause the plugin to be auto-disabled.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum OnError {
    /// Pipeline halts and error propagates. Fail-safe enforcement.
    #[default]
    Fail,

    /// Error logged, pipeline continues. For non-critical plugins.
    Ignore,

    /// Plugin auto-disabled after error. Prevents repeated failures.
    Disable,
}

impl fmt::Display for OnError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Fail => write!(f, "fail"),
            Self::Ignore => write!(f, "ignore"),
            Self::Disable => write!(f, "disable"),
        }
    }
}

#[cfg(test)]
#[allow(clippy::expect_used, clippy::unwrap_used, reason = "tests")]
mod tests {
    use super::*;
    use crate::extensions::{MCPExtension, MetaExtension, SecurityExtension, SubjectExtension};
    use crate::hooks::payload::Extensions;

    // The mode predicates decide whether a plugin is allowed to block the
    // pipeline or rewrite the payload. Nothing called them, so a wrong answer
    // would either let an audit-only plugin deny a request or stop a sequential
    // one from enforcing anything.

    #[test]
    fn disabled_is_the_only_mode_that_is_not_a_dispatch_phase() {
        assert!(!PluginMode::Disabled.is_dispatch_phase());
        for mode in [
            PluginMode::Sequential,
            PluginMode::Transform,
            PluginMode::Audit,
            PluginMode::Concurrent,
            PluginMode::FireAndForget,
        ] {
            assert!(mode.is_dispatch_phase(), "{mode} must be a dispatch phase");
        }
    }

    #[test]
    fn only_blocking_modes_can_block() {
        assert!(PluginMode::Sequential.can_block());
        assert!(PluginMode::Concurrent.can_block());
        for mode in [
            PluginMode::Transform,
            PluginMode::Audit,
            PluginMode::FireAndForget,
            PluginMode::Disabled,
        ] {
            assert!(!mode.can_block(), "{mode} must not be able to block");
        }
    }

    /// `Concurrent` can block but must not modify: concurrent plugins race, so a
    /// payload rewrite would depend on completion order.
    #[test]
    fn only_sequential_and_transform_can_modify() {
        assert!(PluginMode::Sequential.can_modify());
        assert!(PluginMode::Transform.can_modify());
        for mode in [
            PluginMode::Concurrent,
            PluginMode::Audit,
            PluginMode::FireAndForget,
            PluginMode::Disabled,
        ] {
            assert!(!mode.can_modify(), "{mode} must not be able to modify");
        }
    }

    #[test]
    fn fire_and_forget_and_disabled_are_not_awaited() {
        assert!(!PluginMode::FireAndForget.is_awaited());
        assert!(!PluginMode::Disabled.is_awaited());
        for mode in [
            PluginMode::Sequential,
            PluginMode::Transform,
            PluginMode::Audit,
            PluginMode::Concurrent,
        ] {
            assert!(mode.is_awaited(), "{mode} must be awaited");
        }
    }

    /// The `Display` strings are the serde wire names, so they appear in config
    /// and in logs. A drift here silently changes what an operator has to write.
    #[test]
    fn mode_and_on_error_display_as_their_config_spellings() {
        assert_eq!(PluginMode::Sequential.to_string(), "sequential");
        assert_eq!(PluginMode::Transform.to_string(), "transform");
        assert_eq!(PluginMode::Audit.to_string(), "audit");
        assert_eq!(PluginMode::Concurrent.to_string(), "concurrent");
        assert_eq!(PluginMode::FireAndForget.to_string(), "fire_and_forget");
        assert_eq!(PluginMode::Disabled.to_string(), "disabled");

        assert_eq!(OnError::Fail.to_string(), "fail");
        assert_eq!(OnError::Ignore.to_string(), "ignore");
        assert_eq!(OnError::Disable.to_string(), "disable");
    }

    // ---- conditions -------------------------------------------------------

    fn cfg_with(conditions: Vec<PluginCondition>) -> PluginConfig {
        PluginConfig {
            name: "p".into(),
            conditions,
            ..Default::default()
        }
    }

    fn ext_for_entity(entity_type: &str, entity_name: &str) -> Extensions {
        Extensions {
            meta: Some(Arc::new(MetaExtension {
                entity_type: Some(entity_type.to_owned()),
                entity_name: Some(entity_name.to_owned()),
                ..Default::default()
            })),
            ..Default::default()
        }
    }

    /// No conditions means the plugin always runs. This is the default an
    /// operator gets by omitting the block, so it must not accidentally gate.
    #[test]
    fn no_conditions_always_passes() {
        assert!(cfg_with(vec![]).passes_conditions(&Extensions::default()));
    }

    /// The entity name is read from the slot matching `entity_type`, so a tool
    /// condition must not be satisfied by a prompt of the same name. Otherwise a
    /// plugin scoped to one entity kind would fire on another.
    #[test]
    fn an_entity_name_only_matches_within_its_own_entity_type() {
        let cfg = cfg_with(vec![PluginCondition {
            tools: Some(["search".to_owned()].into()),
            ..Default::default()
        }]);
        assert!(cfg.passes_conditions(&ext_for_entity("tool", "search")));
        assert!(
            !cfg.passes_conditions(&ext_for_entity("prompt", "search")),
            "a prompt named `search` must not satisfy a tools condition"
        );
        assert!(
            !cfg.passes_conditions(&ext_for_entity("resource", "search")),
            "a resource named `search` must not satisfy a tools condition"
        );
    }

    #[test]
    fn prompt_and_resource_conditions_read_their_own_slots() {
        let prompt_cfg = cfg_with(vec![PluginCondition {
            prompts: Some(["summarize".to_owned()].into()),
            ..Default::default()
        }]);
        assert!(prompt_cfg.passes_conditions(&ext_for_entity("prompt", "summarize")));
        assert!(!prompt_cfg.passes_conditions(&ext_for_entity("tool", "summarize")));

        let resource_cfg = cfg_with(vec![PluginCondition {
            resources: Some(["doc-1".to_owned()].into()),
            ..Default::default()
        }]);
        assert!(resource_cfg.passes_conditions(&ext_for_entity("resource", "doc-1")));
        assert!(!resource_cfg.passes_conditions(&ext_for_entity("tool", "doc-1")));
    }

    /// An unknown `entity_type` yields no name in any slot, so a name-based
    /// condition cannot match. Fail closed rather than matching everything.
    #[test]
    fn an_unknown_entity_type_satisfies_no_name_condition() {
        let cfg = cfg_with(vec![PluginCondition {
            tools: Some(["search".to_owned()].into()),
            ..Default::default()
        }]);
        assert!(!cfg.passes_conditions(&ext_for_entity("webhook", "search")));
    }

    /// A condition naming a value the request does not carry at all must not
    /// pass. This is the case that decides whether an absent field reads as
    /// "no constraint" or as "does not match", and it has to be the latter.
    #[test]
    fn a_condition_on_an_absent_field_does_not_pass() {
        let cfg = cfg_with(vec![PluginCondition {
            server_ids: Some(["srv-1".to_owned()].into()),
            ..Default::default()
        }]);
        assert!(
            !cfg.passes_conditions(&Extensions::default()),
            "no server_id present, so a server_ids condition must not match"
        );
    }

    /// `server_id` is sourced from whichever of tool, resource or prompt carries
    /// one, so each fallback needs to work.
    #[test]
    fn server_id_is_sourced_from_tool_resource_or_prompt() {
        let cfg = cfg_with(vec![PluginCondition {
            server_ids: Some(["srv-1".to_owned()].into()),
            ..Default::default()
        }]);
        for slot in ["tool", "resource", "prompt"] {
            let mut mcp = MCPExtension::default();
            match slot {
                "tool" => {
                    mcp.tool = Some(crate::extensions::mcp::ToolMetadata {
                        server_id: Some("srv-1".to_owned()),
                        ..Default::default()
                    });
                },
                "resource" => {
                    mcp.resource = Some(crate::extensions::mcp::ResourceMetadata {
                        server_id: Some("srv-1".to_owned()),
                        ..Default::default()
                    });
                },
                _ => {
                    mcp.prompt = Some(crate::extensions::mcp::PromptMetadata {
                        server_id: Some("srv-1".to_owned()),
                        ..Default::default()
                    });
                },
            }
            let ext = Extensions {
                mcp: Some(Arc::new(mcp)),
                ..Default::default()
            };
            assert!(
                cfg.passes_conditions(&ext),
                "server_id on the {slot} slot must satisfy the condition"
            );
        }
    }

    /// The tenant is read out of the subject's `tenant` claim, which is how a
    /// multi-tenant deployment scopes a plugin to one tenant.
    #[test]
    fn tenant_is_read_from_the_subject_tenant_claim() {
        let cfg = cfg_with(vec![PluginCondition {
            tenant_ids: Some(["acme".to_owned()].into()),
            ..Default::default()
        }]);
        let with_tenant = |tenant: &str| {
            let mut sub = SubjectExtension::default();
            sub.claims
                .insert("tenant".to_owned(), serde_json::json!(tenant));
            Extensions {
                security: Some(Arc::new(SecurityExtension {
                    subject: Some(sub),
                    ..Default::default()
                })),
                ..Default::default()
            }
        };
        assert!(cfg.passes_conditions(&with_tenant("acme")));
        assert!(
            !cfg.passes_conditions(&with_tenant("other")),
            "a different tenant must not satisfy the condition"
        );
    }

    /// A numeric tenant claim still matches the text an operator configured.
    /// Before subject claims held `Value` the claim map stringified it, so a
    /// deployment whose `IdP` mints `"tenant": 42` matched `tenant_ids: ["42"]`.
    /// A condition that quietly stopped matching would stop running the plugin
    /// it scopes — including one that enforces something.
    #[test]
    fn a_numeric_tenant_claim_still_matches_configured_text() {
        let cfg = cfg_with(vec![PluginCondition {
            tenant_ids: Some(["42".to_owned()].into()),
            ..Default::default()
        }]);
        let mut sub = SubjectExtension::default();
        sub.claims
            .insert("tenant".to_owned(), serde_json::json!(42));
        let ext = Extensions {
            security: Some(Arc::new(SecurityExtension {
                subject: Some(sub),
                ..Default::default()
            })),
            ..Default::default()
        };
        assert!(cfg.passes_conditions(&ext));
    }
}