Rust API Reference

Import public items from the patronus_ark crate.

Public Exports

// SPDX-License-Identifier: GPL-3.0-only
pub mod assets;
#[allow(dead_code, unused_imports)]
mod cache;
pub mod detectors;
mod diagnostics;
pub mod dynamic_pii;
pub mod external_l1;
pub mod gliner_onnx_engine;
pub mod ml;
pub mod normalization;
pub mod pipeline;
pub mod post_prediction;
pub mod threat;
pub mod types;

pub use cache::{
    CacheEncryptionConfig, CacheError, CacheWriteMode, ExactCacheConfig, MemoryCacheConfig,
    PersistentCacheConfig, WriteBehindConfig,
};
pub use dynamic_pii::{
    DynamicPiiConditionalLabels, DynamicPiiConfig, DynamicPiiExecutionGate,
    DynamicPiiResultCondition, EvidenceSpan,
};
pub use external_l1::{ExternalL1Detector, ExternalL1Input};
pub use normalization::{canonical_security_text_v1, normalize_text, TextNormalizationConfig};
pub use pipeline::{Pipeline, SecurityGateway};
pub use post_prediction::{CredentialTemplateHook, LocalPathPersonHook, PostPredictionHook};
pub use types::{
    ConditionalPipelineGate, DecisionCandidate, DecisionEnvelope, DecisionProvenance,
    DecisionRecommendation, DecisionResult, DecisionTerminality, EffectiveL3PipelinePolicy,
    EvaluationResult, ExecutionBackend, GateExpression, GateResult, L3AggregationStrategy,
    L3ClusteringStrategy, L3EarlyExitMode, L3PipelineEarlyExit, L3PipelinePolicy, L3ProgressMode,
    L3SchedulerPolicy, L3Strategy, LabelScore, LayerResult, MetadataCondition, NtdbOperatingPoint,
    OnnxBatchMode, OnnxRuntimeOptions, QueuedSecurityEvent, QueuedSecurityProgress,
    QueuedSecurityScanResult, RequestId, ResultCondition, ScanExecution, ScanGateMatrix,
    SecurityAssetProgress, SecurityAssetProgressCallback, SecurityAssetReadiness, SecurityCategory,
    SecurityFailure, SecurityFailureKind, SecurityFailureStage, SecurityLevel,
    SecurityLevelReadiness, SecurityRequestCompletion, SecurityRequestState,
    SecurityRuntimeReadiness, SecurityScanResult,
};

Core Gateway

pub struct SecurityGateway {
    core: Arc<SecurityGatewayCore>,
    queue_sender: OnceLock<mpsc::Sender<request_queue::QueueWork>>,
}

Main scanner gateway for native and model-backed security categories.

pub fn flush_cache(&self) -> Result<(), crate::CacheError>;

Flush queued persistent cache writes. Memory-only gateways are a no-op.

pub fn reset_cache_connections(&self) -> Result<(), crate::CacheError>;

Flush queued persistent cache writes and reopen storage on the next cache access.

pub fn reset_cache(&self, until_unix_ms: u64) -> Result<usize, crate::CacheError>;

Remove hot and persistent cache records created before until_unix_ms.

pub fn cache_storage_location(&self) -> Option<PathBuf>;

Explicit persistent cache location configured for this gateway.

pub fn set_queue_worker_count(&self, worker_count: usize);

Set the number of Ark queue workers spawned on first queued request.

pub fn set_onnx_runtime_options(&self, options: crate::OnnxRuntimeOptions);

Set ONNX Runtime session options for subsequent scans.

pub fn new(
    categories: Vec<SecurityCategory>,
    model_dir: Option<PathBuf>,
    download_files: bool,
) -> Self;

Create a gateway with SecurityLevel::L2 as the maximum level.

pub fn with_max_level(
    categories: Vec<SecurityCategory>,
    max_level: SecurityLevel,
    model_dir: Option<PathBuf>,
    download_files: bool,
) -> Self;

Create a gateway with an explicit maximum security level.

pub fn with_download_categories(
    categories: Vec<SecurityCategory>,
    max_level: SecurityLevel,
    model_dir: Option<PathBuf>,
    download_files: bool,
    download_categories: Option<Vec<SecurityCategory>>,
) -> Self;

Create a gateway with an optional per-category asset download allowlist.

When download_categories is None, all configured categories may download missing assets if download_files is true.

pub fn try_with_download_categories_and_cache(
    categories: Vec<SecurityCategory>,
    max_level: SecurityLevel,
    model_dir: Option<PathBuf>,
    download_files: bool,
    download_categories: Option<Vec<SecurityCategory>>,
    cache_config: crate::ExactCacheConfig,
) -> Result<Self, crate::CacheError>;

Create a gateway with lifecycle-scoped exact-cache configuration.

Persistent caching is enabled only when cache_config.persistent contains an explicit storage location. Requests cannot override it.

pub fn categories(&self) -> &[SecurityCategory];

Categories configured for scan_all.

pub fn max_level(&self) -> SecurityLevel;

Maximum level evaluated for configured categories.

pub fn runtime_readiness(&self) -> SecurityRuntimeReadiness;

Return runtime readiness for the currently configured levels and models.

pub fn register_external_l1(
    &self,
    detector: Arc<dyn ExternalL1Detector>,
) -> Result<(), String>;

Register an external L1 heuristic for the category returned by the detector.

Detectors run after the built-in L1 heuristics in registration order.

pub fn set_execution_gates(&self, gates: ScanGateMatrix);

Replace the execution gate matrix used by subsequent scans.

pub fn set_onnx_batch_mode(&self, mode: OnnxBatchMode);

Replace the ONNX batch mode used by subsequent batch scans.

pub fn set_execution_backend(&self, backend: ExecutionBackend);

Replace the execution backend and apply its default L3 mode.

pub fn set_ntdb_operating_point(&self, point: NtdbOperatingPoint);

Select the calibrated NTDB operating point used by subsequent scans.

pub fn set_ntdb_decision_threshold_point(&self, point: NtdbOperatingPoint);

Select the calibrated NTDB final-decision threshold set used by subsequent scans.

pub fn set_l3_strategy(&self, strategy: crate::L3Strategy);

Select dedicated per-pipeline L3 models or the shared multi-head model.

pub fn stop_l3_models(&self);

Unload resident L3 model sessions while keeping registered model metadata.

Subsequent L3 scans can reload the same configured models without another gateway construction or asset warmup.

pub fn l3_strategy(&self) -> crate::L3Strategy;

Return the active global L3 model strategy.

pub fn ntdb_operating_point(&self) -> NtdbOperatingPoint;

Return the calibrated NTDB operating point used by subsequent scans.

pub fn ntdb_decision_threshold_point(&self) -> NtdbOperatingPoint;

Return the calibrated NTDB final-decision threshold set used by subsequent scans.

pub fn set_dynamic_pii_config(&self, config: DynamicPiiConfig) -> Result<(), String>;

Replace the pipeline-specific dynamic-pii configuration.

pub fn dynamic_pii_config(&self) -> DynamicPiiConfig;

Return the currently configured dynamic-pii settings.

Asset And Runtime Lifecycle

pub fn warmup(&mut self) -> Result<(), SecurityFailure>;

Backwards-compatible combined lifecycle. New integrations should call prepare_assets in their delivery window and warmup_from_local_assets when starting their runtime.

pub fn prepare_assets(&self) -> Result<SecurityAssetReadiness, SecurityFailure>;

Download and verify configured model assets without initializing ONNX, tokenizers, executors, workers, or model sessions.

pub fn prepare_assets_with_progress(
    &self,
    progress: SecurityAssetProgressCallback,
) -> Result<SecurityAssetReadiness, SecurityFailure>;

Download and verify configured model assets while reporting per-model file progress. Callbacks may run concurrently on asset download threads.

pub fn asset_readiness(&self) -> SecurityAssetReadiness;

Inspect configured model assets without downloading or warming them.

pub fn warmup_from_local_assets(&mut self) -> Result<(), SecurityFailure>;

Initialize all configured model runtimes strictly from local assets. This method has no download path regardless of the gateway's download policy.

Queued Request API

pub fn scan_category(&self, category: SecurityCategory, text: &str) -> Vec<SecurityScanResult>;

Scan text with a single category.

pub fn enqueue(&self, text: impl Into<String>, gates: Option<ScanGateMatrix>) -> RequestId;

Submit a scan to the background L1/L2 worker and return immediately with its request id. Results and completion are published through [SecurityGateway::consume_next_event].

pub fn enqueue_with_metadata(
    &self,
    text: impl Into<String>,
    metadata: serde_json::Value,
    gates: Option<ScanGateMatrix>,
) -> RequestId;

Submit a scan with caller-provided request metadata used by conditional gates.

pub fn enqueue_with_options(
    &self,
    text: impl Into<String>,
    metadata: serde_json::Value,
    gates: Option<ScanGateMatrix>,
    ntdb_decision_threshold_point: Option<crate::NtdbOperatingPoint>,
) -> RequestId;

Submit a scan with request-local execution options.

pub fn enqueue_categories(
    &self,
    categories: Vec<SecurityCategory>,
    text: impl Into<String>,
    gates: Option<ScanGateMatrix>,
) -> RequestId;

Submit a scan with a caller-provided category subset to the background worker. This method returns a request id, not scan results.

pub fn enqueue_categories_with_metadata(
    &self,
    categories: Vec<SecurityCategory>,
    text: impl Into<String>,
    metadata: serde_json::Value,
    gates: Option<ScanGateMatrix>,
) -> RequestId;

Submit selected categories with request-local metadata.

pub fn enqueue_categories_with_options(
    &self,
    categories: Vec<SecurityCategory>,
    text: impl Into<String>,
    metadata: serde_json::Value,
    gates: Option<ScanGateMatrix>,
    ntdb_decision_threshold_point: Option<crate::NtdbOperatingPoint>,
) -> RequestId;

Submit selected categories with request-local execution options.

pub fn enqueue_input(
    &self,
    input: ExternalL1Input,
    gates: Option<ScanGateMatrix>,
) -> RequestId;

Submit one category scan to the background worker.

pub fn consume_next_event(&self, timeout: Option<Duration>) -> Option<QueuedSecurityEvent>;

Consume the next result or terminal event published by the queue.

pub fn has_request(&self, request_id: &str) -> bool;

Return whether a request is running or its terminal event is still queued.

pub fn request_state(&self, request_id: &str) -> Option<SecurityRequestState>;

Return the lifecycle state until the request's terminal event is consumed.

pub fn is_finished(&self, request_id: &str) -> Option<bool>;

Return whether a known request has reached a terminal state.

pub fn scan_categories(
    &self,
    categories: &[SecurityCategory],
    text: &str,
) -> Vec<SecurityScanResult>;

Scan text with a caller-provided category subset.

pub fn scan_input(&self, input: &ExternalL1Input) -> Vec<SecurityScanResult>;

Scan one category through native and registered external scanners.

pub fn scan_all(&self, text: &str) -> Vec<SecurityScanResult>;

Scan text with every category configured on this gateway.

External L1 API

pub struct ExternalL1Input {
    pub category: SecurityCategory,
    pub text: Arc<str>,
}

Input passed to an externally registered L1 heuristic.

pub fn new(category: SecurityCategory, text: impl Into<String>) -> Self;

Create an input for one security category.

pub fn from_shared_text(category: SecurityCategory, text: Arc<str>) -> Self;

Create an input that shares request text with other categories.

pub trait ExternalL1Detector: Send + Sync {
    /// Stable detector id used in the public model name `external:<id>`.
    fn id(&self) -> &'static str;

    /// Security pipeline extended by this detector.
    fn category(&self) -> SecurityCategory;

    /// Evaluate one request input.
    fn evaluate(&self, input: &ExternalL1Input) -> EvaluationResult;
}

An application-provided L1 heuristic attached to one security category.

Dynamic PII Types

pub enum DynamicPiiExecutionGate {
    /// Run whenever the category and L3 model are enabled.
    Always,
    /// Run when a source pipeline returns one of the configured results.
    IfResultIn {
        pipeline: String,
        results: Vec<String>,
    },
    /// Run only after a source pipeline finishes without a usable result.
    IfNoResult { pipeline: String },
}

Request-local condition controlling whether dynamic-pii runs.

pub struct DynamicPiiResultCondition {
    pub pipeline: String,
    pub results: Vec<String>,
}

Positive source-result condition used by a conditional label rule.

pub struct DynamicPiiConditionalLabels {
    pub labels: Vec<String>,
    pub when: DynamicPiiResultCondition,
}

Labels activated when another pipeline returns a configured result.

pub struct DynamicPiiConfig {
    /// Canonical entity labels; GLiNER receives underscores as spaces in this order.
    pub labels: Vec<String>,
    /// Default entity score threshold.
    pub threshold: f32,
    /// Optional threshold overrides keyed by entity label.
    #[serde(default)]
    pub label_thresholds: HashMap<String, f32>,
    /// Request-local gate deciding whether this pipeline runs.
    #[serde(default)]
    pub execution_gate: DynamicPiiExecutionGate,
    /// Additional labels activated by final source-pipeline results.
    #[serde(default)]
    pub conditional_labels: Vec<DynamicPiiConditionalLabels>,
    /// Maximum accepted UTF-8 input size.
    pub max_text_bytes: usize,
    /// Maximum whitespace-token count per GLiNER chunk.
    pub chunk_size_words: usize,
    /// Repeated whitespace-token count between neighboring chunks.
    pub chunk_overlap_words: usize,
    /// Minimum inference deadline for one resolved L3 job.
    pub timeout_ms: u64,
    /// Maximum time the resolved job may wait in the shared L3 queue.
    pub queue_timeout_ms: u64,
    /// Additional inference budget granted for every planned GLiNER chunk.
    pub timeout_per_chunk_ms: u64,
    /// Upper bound for the adaptive inference budget.
    pub max_timeout_ms: u64,
}

Pipeline-specific configuration for the L3-only dynamic-pii scanner.

pub fn validated(mut self) -> Result<Self, String>;

Validate and normalize this configuration.

pub struct EvidenceSpan {
    pub label: String,
    pub text: String,
    pub score: f64,
    pub start_byte: usize,
    pub end_byte: usize,
    pub start_char: usize,
    pub end_char: usize,
}

Exact evidence span returned by an entity-producing pipeline.

Result And Category Types

pub type RequestId = String;

No public documentation is available yet.

pub enum SecurityRequestState {
    /// At least one planned scanner or promoted L3 job can still publish an event.
    Running,
    /// All planned work has reached a terminal outcome.
    Finished(SecurityRequestCompletion),
}

Lifecycle state for an accepted queued request until its terminal event is consumed.

pub enum SecurityRequestCompletion {
    /// Every planned scanner completed without a failure.
    Complete,
    /// At least one usable result and at least one failure were produced.
    Degraded { failures: Vec<SecurityFailure> },
    /// No planned scanner produced a usable result.
    Failed { failures: Vec<SecurityFailure> },
}

Terminal outcome for one accepted queued request.

pub struct SecurityFailure {
    pub stage: SecurityFailureStage,
    pub level: Option<SecurityLevel>,
    pub detector_id: Option<String>,
    pub kind: SecurityFailureKind,
    pub retryable: bool,
    pub message: String,
}

Typed failure attached to one scanner stage.

pub enum SecurityFailureStage {
    Warmup,
    Asset,
    Scanner,
    Inference,
    Queue,
    Worker,
}

Runtime stage at which a security operation failed.

pub enum SecurityFailureKind {
    NotReady,
    MissingAsset,
    IntegrityFailure,
    InitializationFailure,
    InferenceFailure,
    Timeout,
    WorkerUnavailable,
    Internal,
}

Stable failure classification for product logic.

pub struct SecurityRuntimeReadiness {
    pub l1: SecurityLevelReadiness,
    pub l2: SecurityLevelReadiness,
    pub l3: SecurityLevelReadiness,
}

Readiness of the configured scanner runtime by security level.

pub struct SecurityAssetReadiness {
    pub l2: SecurityLevelReadiness,
    pub l3: SecurityLevelReadiness,
}

Readiness of model assets on disk before runtime warmup.

L1 is intentionally absent because native L1 scanners require no model assets. Runtime readiness remains a separate contract.

pub struct SecurityAssetProgress {
    /// Pipeline category whose assets are currently being prepared.
    pub category: SecurityCategory,
    /// Public model identifier from the asset manifest.
    pub model: String,
    /// Files already present or downloaded for this model.
    pub completed_files: usize,
    /// Total files required by this model.
    pub total_files: usize,
}

Progress emitted while configured model assets are downloaded.

pub type SecurityAssetProgressCallback =
    std::sync::Arc<dyn Fn(SecurityAssetProgress) + Send + Sync>;

Thread-safe callback used by asset preparation workers.

pub enum SecurityLevelReadiness {
    Ready,
    NotConfigured,
    NotReady { failures: Vec<SecurityFailure> },
}

Readiness of one security level before request execution.

pub fn as_str(self) -> &'static str;

No public documentation is available yet.

pub fn as_str(self) -> &'static str;

No public documentation is available yet.

pub enum QueuedSecurityEvent {
    /// One usable scanner result.
    Result(QueuedSecurityScanResult),
    /// Non-authoritative progress for UI status.
    Progress(QueuedSecurityProgress),
    /// Non-authoritative interim result for UI preview.
    Provisional(QueuedSecurityScanResult),
    /// The unique terminal event for an accepted request.
    Finished {
        request_id: RequestId,
        completion: SecurityRequestCompletion,
    },
}

Ordered event published by the queue.

pub fn request_id(&self) -> &str;

Return the request id carried by this event.

pub struct QueuedSecurityProgress {
    pub request_id: RequestId,
    pub category: String,
    pub model: String,
    pub stage: String,
    pub completed_chunks: usize,
    pub total_chunks: usize,
    pub inferred_chunks: usize,
    pub propagated_chunks: usize,
    pub cache_hits: usize,
    pub early_exit: bool,
    pub coverage: f64,
    pub details: HashMap<String, serde_json::Value>,
}

Progress emitted while L3 resolves a multi-chunk request.

pub struct QueuedSecurityScanResult {
    /// Request id returned by `SecurityGateway::enqueue`.
    pub request_id: RequestId,
    /// Complete classifier result published by L1/L2 or the L3 worker.
    pub result: SecurityScanResult,
}

A completed queued scan result together with the request that produced it.

pub struct EvaluationResult {
    /// Stable class label returned by the scanner.
    pub class_name: String,
    /// Confidence score in the inclusive range `0.0..=1.0` when available.
    pub confidence: f64,
    /// Security level that produced the decision.
    pub level: String,
}

A single classifier decision before it is wrapped in a public scan result.

pub struct LayerResult {
    /// Security level for this layer, for example `L1` or `L2`.
    pub level: String,
    /// Layer implementation type such as `native`, `l2`, or `l3`.
    pub layer_type: String,
    /// Stable class label returned by this layer.
    pub class_name: String,
    /// Confidence score in the inclusive range `0.0..=1.0` when available.
    pub confidence: f64,
    /// Whether the layer produced a matched decision.
    pub matched: bool,
    /// Wall-clock time spent in this layer, in milliseconds.
    pub duration_ms: f64,
    /// Threshold values that were applied by the layer.
    pub thresholds: HashMap<String, f64>,
    /// Layer-specific metadata, kept as JSON values for forward compatibility.
    pub details: HashMap<String, serde_json::Value>,
}

Per-layer evidence for a scan result.

pub struct SecurityScanResult {
    /// Category that was scanned, for example `injection` or `dlp`.
    pub category: String,
    /// Stable class label for the final decision.
    pub class_name: String,
    /// Final confidence score in the inclusive range `0.0..=1.0` when available.
    pub confidence: f64,
    /// Highest layer that contributed the final decision.
    pub level: String,
    /// Model or native scanner name that produced the final decision.
    pub model: String,
    /// Sum of recorded layer durations, in milliseconds.
    pub duration_ms: f64,
    /// Ordered layer evidence that explains the final decision.
    pub layers: Vec<LayerResult>,
    /// Internal L2 chunk outputs reused by L3 planning. This field is cleared
    /// before results are published outside the gateway.
    #[doc(hidden)]
    pub internal_l2_chunk_outputs: Vec<crate::ml::ntdb_executor::L2ChunkOutput>,
    /// Exact entity evidence returned by span-producing pipelines.
    pub evidence_spans: Vec<crate::dynamic_pii::EvidenceSpan>,
    /// Per-label scores for multi-label classifier outputs.
    pub label_scores: Vec<LabelScore>,
    /// Structured classifier decision contract for policy consumers.
    pub decision: Option<DecisionEnvelope>,
}

Public scan result returned by SecurityGateway methods.

pub struct DecisionEnvelope {
    pub schema_version: String,
    pub final_result: DecisionResult,
    pub decision_candidate: Option<DecisionCandidate>,
    pub recommendation: DecisionRecommendation,
    pub candidates: Vec<DecisionCandidate>,
    pub terminality: DecisionTerminality,
    pub provenance: DecisionProvenance,
}

Stable classifier decision envelope for downstream policy evaluation.

pub struct DecisionResult {
    pub class_name: String,
    pub confidence: f64,
    pub source: String,
}

Final Ark verdict recorded inside a decision envelope.

pub struct DecisionCandidate {
    pub source: String,
    pub class_name: String,
    pub confidence: f64,
    pub acceptance_threshold: f64,
    pub accepted: bool,
    pub evidence: Option<HashMap<String, f64>>,
}

One typed classifier candidate considered by final-decision arbitration.

pub struct DecisionRecommendation {
    pub accepted: bool,
    pub final_arbitration: String,
    pub operating_point: String,
    pub acceptance_threshold: Option<f64>,
}

Ark's calibrated default recommendation for a classifier result.

pub struct DecisionTerminality {
    pub completion: String,
    pub degraded: bool,
    pub degradation_reason: Option<String>,
}

Terminal request state relevant to decision consumers.

pub struct DecisionProvenance {
    pub ark_version: String,
    pub schema_version: String,
    pub model: String,
}

Minimal provenance for a classifier decision envelope.

pub struct LabelScore {
    pub label: String,
    pub confidence: f64,
    pub matched: bool,
}

One scored label returned by a multi-label classifier head.

pub enum SecurityLevel {
    /// Native rule-based checks only.
    L1 = 1,
    /// Native checks plus L2 model-backed classifiers when assets are available.
    L2 = 2,
    /// Native, L2, and L3 model-backed classifiers when assets are available.
    L3 = 3,
}

Maximum scanner depth to run.

pub fn as_str(self) -> &'static str;

Return the canonical uppercase level string.

pub enum OnnxBatchMode {
    /// Keep the existing lazy per-text ONNX execution path.
    LazyBatches,
    /// Execute all L3 fallback texts as one ONNX tensor batch where possible.
    TensorBatch,
}

How model pipelines execute ONNX L3 fallback batches.

pub fn as_str(self) -> &'static str;

Return the canonical snake_case mode string.

pub enum NtdbOperatingPoint {
    BestF1,
    BestPromote,
    BestFprInF1,
    BestFnrInF1,
    BestLatencyInF1,
}

Calibrated NTDB operating point selected from each package manifest.

pub fn as_str(self) -> &'static str;

Return the manifest key for this operating point.

pub enum ExecutionBackend {
    /// Keep conservative CPU defaults unless a caller overrides execution mode.
    Auto,
    /// CPU execution: prefer lazy L3 execution and low concurrency.
    Cpu,
    /// Platform GPU alias: DirectML on Windows, CUDA on Linux, unsupported on macOS.
    Gpu,
    /// CoreML execution provider.
    CoreMl,
    /// CUDA execution provider.
    Cuda,
    /// DirectML execution provider.
    DirectMl,
    /// TensorRT execution provider.
    TensorRt,
}

Runtime backend profile used to choose default L3 execution behavior.

pub enum L3Strategy {
    /// Each promoted pipeline executes its own L3 model.
    Dedicated,
    /// Promoted classifier pipelines share one request-local multi-head model run.
    Multi,
}

Physical L3 classifier topology.

pub fn as_str(self) -> &'static str;

No public documentation is available yet.

pub fn as_str(self) -> &'static str;

Return the canonical snake_case backend string.

pub struct OnnxRuntimeOptions {
    pub intra_threads: Option<usize>,
    pub inter_threads: Option<usize>,
    pub spinning: Option<bool>,
}

Caller-provided ONNX Runtime session options.

pub fn normalized(self) -> Self;

No public documentation is available yet.

pub struct ScanGateMatrix {
    /// Optional L1 override. `None` means enabled.
    pub l1: Option<bool>,
    /// Optional L2 override. `None` means enabled.
    pub l2: Option<bool>,
    /// Optional L3 override. `None` means enabled.
    pub l3: Option<bool>,
    /// Optional per-model or per-native-scanner overrides keyed by result model
    /// names such as `native:mcp_runtime_risk` or `unified-v3-tool-action`.
    pub models: HashMap<String, bool>,
    /// Request-context and prior-result conditions applied before L2 or L3.
    pub conditional: Vec<ConditionalPipelineGate>,
    /// L3 worker scheduling policy.
    pub l3_policy: L3SchedulerPolicy,
}

Caller-controlled execution gates for one scanner execution profile.

Unspecified gates default to enabled. max_level is still enforced by ScanExecution, so a gate can only further restrict the configured scanner.

pub struct L3SchedulerPolicy {
    /// Whether model L3 work should be centrally queued by scan methods.
    pub enabled: bool,
    /// Ordered category/model priority list. Earlier entries run first.
    pub priority: Vec<String>,
    /// Per category/model timeout before an unstarted L3 job degrades.
    pub ttl_ms: HashMap<String, u64>,
    /// Initial execution-cost estimate per category/model. The worker replaces
    /// this gradually with observed wall time while it is running.
    pub estimated_cost_ms: HashMap<String, u64>,
    /// Compute-time credit granted during one fair-scheduling round.
    pub fairness_quantum_ms: u64,
    /// Maximum queue wait before the oldest job bypasses priority and cost.
    pub max_wait_ms: u64,
    /// Multiplier applied to L2 confidence when L3 degrades.
    pub degraded_factor: f64,
    /// Whether L3 may stop once the final class is stable.
    pub early_exit: L3EarlyExitMode,
    /// Whether L3 should emit non-authoritative progress/provisional events.
    pub progress: L3ProgressMode,
    /// Logical chunk ordering strategy. This does not enable tensor batching.
    pub clustering: L3ClusteringStrategy,
    /// Number of high-priority members inferred per similarity cluster for
    /// representative scheduling. Values below 1 are treated as 1.
    pub representatives_per_cluster: usize,
    /// Number of least-similar verification members inferred per cluster for
    /// verify-representative scheduling. Values below 1 are treated as 1.
    pub verify_representatives_per_cluster: usize,
    /// Minimum request-local similarity required to place two chunks in the
    /// same representative cluster.
    pub min_cluster_similarity: f64,
    /// Maximum number of chunks assigned to one representative cluster.
    pub max_cluster_size: usize,
    /// Optional execution-policy overrides keyed by pipeline category or model.
    /// Category keys take precedence over model keys.
    pub pipelines: HashMap<String, L3PipelinePolicy>,
}

Priority and timeout policy for centrally scheduled L3 work.

pub struct L3PipelinePolicy {
    /// Chunk execution strategy. `None` inherits the request-wide default.
    #[serde(default, alias = "execution")]
    pub clustering: Option<L3ClusteringStrategy>,
    /// Representatives inferred from the high-priority side of each cluster.
    #[serde(default)]
    pub representatives_per_cluster: Option<usize>,
    /// Least-similar members used to verify a representative cluster.
    #[serde(default)]
    pub verify_representatives_per_cluster: Option<usize>,
    /// Minimum request-local similarity required for cluster membership.
    #[serde(default)]
    pub min_cluster_similarity: Option<f64>,
    /// Maximum number of members allowed in one cluster.
    #[serde(default)]
    pub max_cluster_size: Option<usize>,
    /// Chunk-output aggregation. `None` keeps the pipeline's built-in rule.
    #[serde(default)]
    pub aggregation: Option<L3AggregationStrategy>,
    /// Early-exit scope. `None` inherits the request-wide default semantics.
    #[serde(default)]
    pub early_exit: Option<L3PipelineEarlyExit>,
}

Optional per-pipeline overrides for L3 chunk execution.

pub enum L3AggregationStrategy {
    AnyPositiveOrHighest {
        positive_class: String,
        threshold: f64,
    },
    HighestRiskAboveThresholdOrConfidence {
        threshold: f64,
    },
    MajorityVoteOrHighest,
}

Configurable aggregation for one L3 pipeline.

pub enum L3PipelineEarlyExit {
    Disabled,
    HeadStable,
    RequestWidePositive,
}

Scope at which a stable per-pipeline L3 decision stops work.

pub struct EffectiveL3PipelinePolicy {
    pub clustering: L3ClusteringStrategy,
    pub representatives_per_cluster: usize,
    pub verify_representatives_per_cluster: usize,
    pub min_cluster_similarity: f64,
    pub max_cluster_size: usize,
    pub aggregation: Option<L3AggregationStrategy>,
    pub early_exit: L3PipelineEarlyExit,
}

Fully resolved execution settings for one pipeline and request.

pub enum L3EarlyExitMode {
    Disabled,
    ClassStable,
}

No public documentation is available yet.

pub enum L3ProgressMode {
    Disabled,
    Progress,
    Provisional,
}

No public documentation is available yet.

pub enum L3ClusteringStrategy {
    Disabled,
    RankOnly,
    Representative,
    VerifyRepresentative,
}

No public documentation is available yet.

pub struct ConditionalPipelineGate {
    /// Phase controlled by this gate. L1 is intentionally not supported.
    pub level: SecurityLevel,
    /// Optional category/model selector. `None` applies to every pipeline at the level.
    #[serde(default)]
    pub pipeline: Option<String>,
    /// Condition that enables a normal gate or activates an `l3_policy` override.
    pub when: GateExpression,
    /// Optional L3 execution-policy override applied when `when` matches.
    /// Policy gates do not suppress the pipeline when the condition is false.
    #[serde(default)]
    pub l3_policy: Option<L3PipelinePolicy>,
}

One conditional L2/L3 pipeline gate.

pub enum GateExpression {
    All(Vec<GateExpression>),
    Any(Vec<GateExpression>),
    Not(Box<GateExpression>),
    Metadata(MetadataCondition),
    Result(ResultCondition),
}

Recursive expression over enqueue metadata and completed L1/L2 results.

pub struct MetadataCondition {
    pub path: String,
    #[serde(default)]
    pub equals: Option<serde_json::Value>,
    #[serde(default, rename = "in")]
    pub in_values: Option<Vec<serde_json::Value>>,
    #[serde(default)]
    pub exists: Option<bool>,
}

Predicate over a dotted path in request metadata.

pub struct ResultCondition {
    pub pipeline: String,
    #[serde(default)]
    pub classes: Vec<String>,
    #[serde(default)]
    pub min_confidence: Option<f64>,
}

Predicate over a previously completed L1/L2 pipeline result.

pub struct GateResult {
    pub pipeline: String,
    pub class_name: String,
    pub confidence: f64,
    pub level: SecurityLevel,
}

Minimal result view exposed to conditional gate evaluation.

pub fn pipeline_policy(&self, category: &str, model: &str) -> EffectiveL3PipelinePolicy;

Resolve request-wide defaults and a category/model override.

pub fn all_enabled() -> Self;

Create a matrix where every level and model is enabled by default.

pub fn levels(l1: bool, l2: bool, l3: bool) -> Self;

Create a matrix with explicit level gates.

pub fn set_level(&mut self, level: SecurityLevel, enabled: bool);

Set one level gate.

pub fn set_model(&mut self, model: impl Into<String>, enabled: bool);

Set one model/native scanner gate.

pub fn with_model(mut self, model: impl Into<String>, enabled: bool) -> Self;

Builder-style model/native scanner gate setter.

pub fn set_conditional(&mut self, gates: Vec<ConditionalPipelineGate>) -> Result<(), String>;

Replace request-context and prior-result gates.

pub fn allows_level(&self, level: SecurityLevel) -> bool;

Return whether the level is allowed by this matrix before max-level enforcement.

pub fn allows_model(&self, model: &str) -> bool;

Return whether the model/native scanner is allowed by this matrix.

pub fn set_l3_policy(&mut self, policy: L3SchedulerPolicy);

Replace the L3 worker scheduling policy.

pub fn validate(&self) -> Result<(), String>;

No public documentation is available yet.

pub struct ScanExecution {
    max_level: SecurityLevel,
    gates: ScanGateMatrix,
    backend: ExecutionBackend,
    onnx_runtime_options: OnnxRuntimeOptions,
    onnx_batch_mode: OnnxBatchMode,
    ntdb_operating_point: NtdbOperatingPoint,
    ntdb_decision_threshold_point: NtdbOperatingPoint,
    l3_strategy: L3Strategy,
    defer_l3: bool,
}

Effective execution state consumed by scan methods and model pipelines.

pub fn new(max_level: SecurityLevel) -> Self;

Create an execution with every gate enabled up to max_level.

pub fn with_gates(max_level: SecurityLevel, gates: ScanGateMatrix) -> Self;

Create an execution with explicit gates up to max_level.

pub fn set_gates(&mut self, gates: ScanGateMatrix);

Replace the gate matrix.

pub fn set_onnx_batch_mode(&mut self, mode: OnnxBatchMode);

Replace the ONNX batch execution mode.

pub fn set_backend(&mut self, backend: ExecutionBackend);

Replace the execution backend and apply its default L3 batch mode.

pub fn set_onnx_runtime_options(&mut self, options: OnnxRuntimeOptions);

Replace ONNX Runtime session options used by L3 ONNX classifiers.

pub fn set_ntdb_operating_point(&mut self, point: NtdbOperatingPoint);

Select the calibrated NTDB operating point used by subsequent scans.

pub fn set_ntdb_decision_threshold_point(&mut self, point: NtdbOperatingPoint);

Select the calibrated NTDB final-decision threshold set.

pub fn set_l3_strategy(&mut self, strategy: L3Strategy);

Select the physical L3 classifier topology.

pub fn set_defer_l3(&mut self, defer_l3: bool);

Set whether L3 should be marked pending instead of executed immediately.

pub fn with_max_level(mut self, max_level: SecurityLevel) -> Self;

Return a copy with a different max-level cap.

pub fn allows_level(&self, level: SecurityLevel) -> bool;

Return whether a level is enabled for this execution after max-level enforcement.

pub fn allows_model(&self, model: &str) -> bool;

Return whether a model/native scanner is enabled for this execution.

pub fn gates(&self) -> &ScanGateMatrix;

Return the matrix backing this execution.

pub fn onnx_batch_mode(&self) -> OnnxBatchMode;

Return the ONNX batch mode backing this execution.

pub fn backend(&self) -> ExecutionBackend;

Return the configured execution backend.

pub fn onnx_runtime_options(&self) -> OnnxRuntimeOptions;

Return the ONNX Runtime session options backing this execution.

pub fn ntdb_operating_point(&self) -> NtdbOperatingPoint;

Return the selected NTDB operating point.

pub fn ntdb_decision_threshold_point(&self) -> NtdbOperatingPoint;

Return the selected NTDB final-decision threshold set.

pub fn l3_strategy(&self) -> L3Strategy;

Return the selected physical L3 classifier topology.

pub fn defer_l3(&self) -> bool;

Return whether L3 should be centrally scheduled.

pub fn l3_policy(&self) -> &L3SchedulerPolicy;

Return the L3 worker policy.

pub fn max_level(&self) -> SecurityLevel;

Return the max-level cap backing this execution.

pub enum SecurityCategory {
    /// Prompt injection and instruction hierarchy attacks.
    Injection,
    /// Data-loss-prevention checks for secrets and sensitive material.
    Dlp,
    /// Personally identifiable information checks.
    Pii,
    /// Dynamic zero-shot entity extraction in the L3 worker.
    DynamicPii,
    /// Sensitive document classification.
    SensitiveDocument,
    /// Tool type classification.
    ToolClass,
    /// Tool operation classification.
    ToolAction,
    /// Multi-label tool source and sink tags.
    ToolTags,
    /// Operational request routing.
    Routing,
    /// Security threat classification.
    Threat,
}

Supported scanner category.

pub fn as_str(self) -> &'static str;

Return the canonical snake_case category string.

pub fn is_unified_classifier(self) -> bool;

Return whether this category is backed by one head of the unified classifier.

Asset Manifest Helpers

pub struct AssetSpec {
    /// Scanner category that owns this asset.
    pub category: SecurityCategory,
    /// Minimum security level that needs this asset.
    pub level: SecurityLevel,
    /// Hugging Face repository identifier.
    pub repo: &'static str,
    /// Immutable Hugging Face commit revision, when the asset is pinned.
    pub revision: Option<&'static str>,
    /// File path inside the Hugging Face repository.
    pub source_path: &'static str,
    /// Relative path below the category cache directory.
    pub destination_path: &'static str,
    /// Whether missing or failed downloads should block `warmup`.
    pub required: bool,
}

A model asset declared in the static download manifest.

pub struct NtdbL2PackageAssetSpec {
    /// Scanner category that owns this package.
    pub category: SecurityCategory,
    /// Minimum security level that needs this package.
    pub level: SecurityLevel,
    /// Public model identifier used by gates and scan results.
    pub model: &'static str,
    /// Hugging Face repository identifier.
    pub repo: &'static str,
    /// Immutable Hugging Face commit revision.
    pub revision: &'static str,
    /// Directory prefix inside the Hugging Face repository.
    pub source_prefix: &'static str,
    /// Relative package directory below the category cache directory.
    pub destination_path: &'static str,
    /// Whether missing or failed downloads should block `warmup`.
    pub required: bool,
}

A manifest-first NTDB v2 L2 package declared for Hugging Face download.

pub struct PipelineModelAssetSpec {
    /// Scanner category that owns this pipeline model.
    pub category: SecurityCategory,
    /// Public model name.
    pub model: &'static str,
    /// Hugging Face repository identifier.
    pub repo: &'static str,
    /// Immutable Hugging Face commit revision.
    pub revision: &'static str,
    /// Relative bundle directory below the model cache.
    pub destination_path: &'static str,
    /// Files required to load and validate the bundle.
    pub files: &'static [&'static str],
}

A revision-pinned model bundle used by a standalone pipeline.

Asset Download Helpers

pub fn category_assets(category: SecurityCategory, max_level: SecurityLevel) -> Vec<AssetSpec>;

Return manifest entries needed for a category up to max_level.

pub fn ntdb_l2_package_assets(
    category: SecurityCategory,
    max_level: SecurityLevel,
) -> Vec<NtdbL2PackageAssetSpec>;

Return NTDB v2 L2 package entries needed for a category up to max_level.

pub fn ntdb_l2_package_asset(
    category: SecurityCategory,
    max_level: SecurityLevel,
    model: &str,
) -> Option<NtdbL2PackageAssetSpec>;

Return the NTDB v2 L2 package entry for a public model name.

pub fn required_assets_present(
    category: SecurityCategory,
    max_level: SecurityLevel,
    target_dir: &Path,
) -> bool;

Check whether all required assets for a category are present in target_dir.

pub fn dynamic_pii_assets_present(target_dir: &Path) -> bool;

Check whether the complete revision-pinned dynamic-pii model is cached.

pub fn download_dynamic_pii_assets(
    target_dir: &Path,
) -> Result<PathBuf, Box<dyn std::error::Error>>;

Download the revision-pinned dynamic-pii GLiNER bundle.

pub fn unified_l3_assets_present(target_dir: &Path) -> bool;

Check whether the complete revision-pinned unified L3 model is cached.

pub fn download_unified_l3_assets(
    target_dir: &Path,
) -> Result<PathBuf, Box<dyn std::error::Error>>;

Download the revision-pinned unified L3 bundle.

pub fn dedicated_l3_asset(category: SecurityCategory) -> Option<PipelineModelAssetSpec>;

Return the revision-pinned dedicated L3 bundle for a classifier category.

pub fn dedicated_l3_assets_present(category: SecurityCategory, target_dir: &Path) -> bool;

Check whether a category's dedicated L3 bundle is cached.

pub fn download_dedicated_l3_assets(
    category: SecurityCategory,
    target_dir: &Path,
) -> Result<Option<PathBuf>, Box<dyn std::error::Error>>;

Download a category's revision-pinned dedicated L3 bundle when it has one.

pub fn download_category_assets(
    category: SecurityCategory,
    max_level: SecurityLevel,
    target_dir: &Path,
) -> Result<(), Box<dyn std::error::Error>>;

Download missing manifest assets for a category into target_dir.

Required asset failures return an error. Optional asset failures are skipped.

pub fn download_ntdb_l2_package(
    category: SecurityCategory,
    max_level: SecurityLevel,
    model: &str,
    target_dir: &Path,
) -> Result<PathBuf, Box<dyn std::error::Error>>;

Download a missing NTDB v2 L2 package from Hugging Face into target_dir.

The package is downloaded manifest-first: manifest.json is fetched from the package prefix, then runtime files referenced by that manifest are downloaded into the same local package tree.

pub fn ntdb_l2_package_manifest_files(
    manifest_json: &str,
) -> Result<Vec<String>, Box<dyn std::error::Error>>;

Return all runtime files referenced by an NTDB v2 package manifest.