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;
pub use patronus_ark_core::{diagnostics, WolfExecutionOptions};
pub mod dynamic_pii;
pub mod external_l1;
pub mod gliner_onnx_engine;
#[cfg(feature = "test-util")]
#[doc(hidden)]
pub mod golden_recipes;
pub mod ml;
pub use patronus_ark_core::normalization;
pub mod pipeline;
pub mod post_prediction;
pub use patronus_ark_core::threat;
pub mod types;

pub use cache::{
    CacheEncryptionConfig, CacheError, CacheWriteMode, ExactCacheConfig, MemoryCacheConfig,
    PersistentCacheConfig, WriteBehindConfig,
};
pub use dynamic_pii::{
    DynamicPiiConditionalLabels, DynamicPiiConfig, DynamicPiiExecutionGate,
    DynamicPiiRequestConfig, DynamicPiiResultCondition, EvidenceSpan, MAX_REQUEST_LABEL_BYTES,
};
pub use external_l1::{ExternalL1Detector, ExternalL1Input};
pub use ml::tokenizer::{ChunkOverlapTokens, MAX_CHUNK_OVERLAP_TOKENS};
pub use normalization::{canonical_security_text_v1, normalize_text, TextNormalizationConfig};
pub use patronus_ark_core::native::{NativeGates, ScoreMode};
pub use pipeline::{Pipeline, SecurityGateway};
pub use post_prediction::{
    CredentialTemplateHook, LocalPathPersonHook, PostPredictionHook, PrivateNetworkDiagnosticHook,
};
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::SyncSender<request_queue::QueueWork>>,
}

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

pub struct DistributedL2Plan {
    pub l1_results: Vec<SecurityScanResult>,
    pub l1_failures: Vec<SecurityFailure>,
    pub categories: Vec<SecurityCategory>,
    pub model_ids: Vec<String>,
    pub pipelines: Vec<DistributedL2Pipeline>,
    pub execution: ScanExecution,
    pub gate_results: Vec<crate::GateResult>,
}

No public documentation is available yet.

pub struct DistributedL2Pipeline {
    pub pipeline_id: String,
    pub category: SecurityCategory,
    pub model_id: String,
    pub public_model: String,
    pub has_l3: bool,
}

No public documentation is available yet.

pub struct DistributedL3Plan {
    pub categories: Vec<SecurityCategory>,
    pub execution: ScanExecution,
    pub gate_results: Vec<crate::GateResult>,
}

No public documentation is available yet.

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_wolf_execution_options(
    &self,
    options: crate::WolfExecutionOptions,
) -> Result<(), String>;

Configure dedicated Wolf windowing and batching for subsequent scans.

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 distributed_ntdb_fingerprints(&self) -> Result<(String, String), String>;

Runtime identities used to reject incompatible distributed batches.

pub fn prepare_distributed_ntdb_chunks(
    &self,
    text: &str,
) -> Result<Vec<PreparedNtdbChunk>, String>;

Tokenize a document once for distributed Package-v4 execution.

pub fn prepare_distributed_ntdb_chunks_with_execution(
    &self,
    text: &str,
    execution: &ScanExecution,
) -> Result<Vec<PreparedNtdbChunk>, String>;

Tokenize a document for distributed execution with request-local options.

pub fn infer_distributed_ntdb_chunks(
    &self,
    model_ids: HashSet<String>,
    chunks: &[PreparedNtdbChunk],
    document_chunk_count: usize,
    operating_point: NtdbOperatingPoint,
) -> Result<Vec<NtdbModelChunkInferences>, String>;

Infer independent, pre-tokenized NTDB chunks without L1 or document aggregation.

pub fn infer_distributed_unified_l3_chunks(
    &self,
    chunks: &[crate::ml::ntdb_executor::NtdbChunkInference],
    execution: &ScanExecution,
) -> Result<Vec<crate::pipeline::DistributedL3ChunkInference>, String>;

Run immediate unified L3 inference for promoted chunks without document aggregation.

pub fn aggregate_distributed_unified_l3_chunks(
    &self,
    chunks: &[crate::pipeline::DistributedL3ChunkInference],
    l2_fallbacks: &[SecurityScanResult],
    execution: &ScanExecution,
    duration_ms: f64,
) -> Result<Vec<SecurityScanResult>, String>;

Aggregate all unified L3 chunk outputs with the normal final result mapping.

pub fn aggregate_distributed_ntdb_chunks(
    &self,
    inferred: &[NtdbModelChunkInferences],
    categories: &[SecurityCategory],
    execution: &ScanExecution,
    duration_ms: f64,
) -> Result<Vec<SecurityScanResult>, String>;

Aggregate all worker L2 evidence and map it through the normal gateway thresholds.

pub fn distributed_execution(&self) -> ScanExecution;

Execute only the normal L1 portion with the gateway's effective configuration.

pub fn scan_distributed_l1(
    &self,
    inputs: &[ExternalL1Input],
    execution: &ScanExecution,
) -> Vec<SecurityScanResult>;

No public documentation is available yet.

pub fn distributed_l2_pipelines(
    &self,
    categories: &[SecurityCategory],
    execution: &ScanExecution,
) -> Vec<DistributedL2Pipeline>;

Resolve canonical distributed pipeline bindings without executing scanners.

pub fn plan_distributed_l2(
    &self,
    inputs: &[ExternalL1Input],
    metadata: &serde_json::Value,
    execution: &ScanExecution,
) -> DistributedL2Plan;

Run L1 and resolve the exact conditional-gate/model plan for distributed L2.

pub fn plan_distributed_l3(
    &self,
    l1_gate_results: &[crate::GateResult],
    l2_results: &[SecurityScanResult],
    metadata: &serde_json::Value,
    execution: &ScanExecution,
) -> DistributedL3Plan;

Resolve L3 policy overrides and eligibility after distributed L2 aggregation.

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 set_shell_command_policy_config(&self, config: ShellPolicyConfig) -> Result<(), String>;

Replace the user policies and allowlist of the shell_command verdict. A loaded pipeline applies them at once (a refused configuration changes nothing); otherwise warmup applies them.

pub fn pin_shell_command_manifest_for_tests(&mut self, manifest_sha256: impl Into<String>);

Accept a shell_command bundle with this manifest instead of the pinned release (synthetic bundles in tests).

pub fn shell_command_policy_config(&self) -> ShellPolicyConfig;

Return the configured shell_command user policies and allowlist.

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_with_chunk_overlap_options(
    &self,
    text: impl Into<String>,
    metadata: serde_json::Value,
    gates: Option<ScanGateMatrix>,
    ntdb_decision_threshold_point: Option<crate::NtdbOperatingPoint>,
    chunk_overlap_tokens: ChunkOverlapTokens,
) -> RequestId;

Submit a scan with caller-provided request-local execution and chunking 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_categories_with_chunk_overlap_options(
    &self,
    categories: Vec<SecurityCategory>,
    text: impl Into<String>,
    metadata: serde_json::Value,
    gates: Option<ScanGateMatrix>,
    ntdb_decision_threshold_point: Option<crate::NtdbOperatingPoint>,
    chunk_overlap_tokens: ChunkOverlapTokens,
) -> RequestId;

Submit selected categories with request-local execution and chunking options.

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

Submit an Ark API request: short-document Injection utility routing, request-local classifier chunk overlap and an optional request-local dynamic-pii configuration. Library callers use the other enqueue methods.

dynamic_pii replaces the gateway's configuration for this request only; build it with [crate::DynamicPiiRequestConfig::resolve]. It is validated again here and rejected before anything is queued.

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.
    #[default]
    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,
}

Extra label group activated on chunks with a matching final source 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.

labels form the stable base GLiNER group for the full input. Conditional labels are never concatenated with that group: every matching rule runs its extra labels separately and only on chunks whose final source-pipeline class matches. Base labels repeated by a conditional rule are removed from its extra call. Dynamic PII waits for referenced source pipelines to reach a terminal result (including L2 results that do not promote), instead of resolving against an interim L2 class.

pub struct DynamicPiiRequestConfig {
    /// Canonical entity labels of the base GLiNER group.
    pub labels: Vec<String>,
    /// Default entity score threshold; the gateway's threshold when absent.
    #[serde(default)]
    pub threshold: Option<f32>,
    /// Optional threshold overrides keyed by entity label.
    #[serde(default)]
    pub label_thresholds: HashMap<String, f32>,
    /// 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>,
}

Request-local labels, thresholds and gates for dynamic-pii.

For one request it replaces the entity fields of the gateway's [DynamicPiiConfig]: labels, label_thresholds, execution_gate and conditional_labels, and threshold when given. Input limits, chunking and timeouts stay those of the gateway.

pub fn resolve(self, base: &DynamicPiiConfig) -> Result<DynamicPiiConfig, String>;

Apply this request configuration to base and validate the result.

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

Validate and normalize this configuration.

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,
    QueueFull,
    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 l1: SecurityLevelReadiness,
    pub l2: SecurityLevelReadiness,
    pub l3: SecurityLevelReadiness,
}

Readiness of model assets on disk before runtime warmup.

Native L1 rule scanners require no model assets, so l1 is configured only for model-backed L1 categories such as shell_command. 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 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 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.
    #[default]
    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,
    #[default]
    BestPromote,
    /// Internal Ark API routing profile: use utility promotion only for an
    /// Injection document with at most two normal chunks.
    ArkApiShortInjectionUtility,
    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 L3Strategy {
    /// Each promoted pipeline executes its own L3 model.
    #[default]
    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 struct ScanGateMatrix {
    /// Native rule, model, mode and `explain` gates, shared with Ark Core.
    pub native: crate::NativeGates,
    /// 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>,
    /// 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 rules use the shared credentials/secrets-only DLP default; other execution gates default to enabled. Diagnostic explain and the scored PII and DLP modes are opt-in. max_level is still enforced by ScanExecution, so a gate can only further restrict the configured scanner.

Deserializes from the one gate schema of every host (Python execution_gates, Ark API gates): the native keys rules, models, pii_mode, dlp_mode and explain, the level switches l1, l2 and l3, conditional and the L3 worker policy l3_policy. Unknown keys and out-of-range values are refused.

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)]
    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;

Explicitly enable all native rules, including opt-in DLP content families.

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_rule(&mut self, rule_id: impl Into<String>, enabled: bool);

Set one stable rule-id gate.

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

Builder-style stable rule-id 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 set_l3_policy(&mut self, policy: L3SchedulerPolicy);

Replace the L3 worker scheduling policy.

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

Refuse out-of-range values: zero counts, costs and fairness quantum, fractions outside 0..=1 and invalid pipeline overrides.

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

Refuse zero counts, fractions outside 0..=1 and an empty positive class.

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,
    chunk_overlap_tokens: usize,
    wolf_execution_options: crate::WolfExecutionOptions,
}

Effective execution state consumed by scan methods and model pipelines.

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

Create an execution with shared rule defaults 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_wolf_execution_options(
    &mut self,
    options: crate::WolfExecutionOptions,
) -> Result<(), String>;

Configure dedicated Wolf execution using the shared Core validation.

pub fn wolf_execution_options(&self) -> crate::WolfExecutionOptions;

No public documentation is available yet.

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 set_chunk_overlap_tokens(&mut self, overlap: usize) -> Result<(), String>;

Set the request-local overlap between adjacent classifier chunks.

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 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 chunk_overlap_tokens(&self) -> usize;

Return the overlap between adjacent classifier chunks.

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.

Synchronous Core API

pub struct ScannerConfig {
    /// Native text-scan categories: `pii`, `dlp` and `injection`.
    pub categories: Vec<SecurityCategory>,
    /// Rule, model, mode and `explain` gates; their keys sit at the top level
    /// of the serialized config.
    #[serde(flatten)]
    pub gates: NativeGates,
    /// Maximum UTF-8 input size; exceeding it is an error. Default: 1 MiB.
    pub max_input_bytes: usize,
    /// Maximum actionable evidence spans; reports are never silently truncated.
    pub max_findings: usize,
    #[cfg(feature = "wolf")]
    pub wolf: Option<crate::wolf::WolfConfig>,
    /// Cat, the shell-command verdict; see [`Scanner::shell_verdict`].
    pub shell: Option<ShellConfig>,
}

Queue-free scanner policy. Defaults to all three native categories, no Wolf and no Cat.

pub enum ScanError {
    #[error("invalid scanner configuration: {0}")]
    Config(String),
    #[error("input exceeds {limit} bytes")]
    InputLimit { limit: usize },
    #[error("findings exceed {limit}")]
    FindingLimit { limit: usize },
    #[error("native detector failed: {0}")]
    Detector(String),
    #[error("scan cancelled")]
    Cancelled,
    #[error("scan deadline exceeded")]
    DeadlineExceeded,
    #[error("asset error: {0}")]
    Asset(String),
    #[error("Wolf inference failed: {0}")]
    Inference(String),
    #[error("shell verdict failed: {0}")]
    Shell(String),
}

No public documentation is available yet.

pub struct ScanReport {
    pub input_bytes: usize,
    pub native: Vec<NativeResult>,
    #[cfg(feature = "wolf")]
    pub wolf: Option<crate::wolf::WolfResult>,
}

Complete scan output; native decisions and model probabilities remain separate.

pub struct Scanner {
    config: ScannerConfig,
    native: NativeEngine,
    #[cfg(feature = "wolf")]
    wolf: Option<crate::wolf::WolfRunner>,
    shell: Option<ShellRiskPipeline>,
}

No public documentation is available yet.

pub fn new(config: ScannerConfig) -> Result<Self, ScanError>;

Initialize native detectors and warm/verify an explicitly configured local Wolf bundle.

pub fn new_with_wolf_options(
    config: ScannerConfig,
    options: crate::WolfExecutionOptions,
) -> Result<Self, ScanError>;

Initialize with explicit Wolf windowing and batching; native stages are unchanged.

pub fn scan(&mut self, text: &str) -> Result<ScanReport, ScanError>;

Run all configured stages synchronously. Any incomplete stage returns an error.

pub fn scan_categories(
    &mut self,
    text: &str,
    categories: &[SecurityCategory],
) -> Result<ScanReport, ScanError>;

Run the selected categories with the existing scanner and the same resource limits. The selection is intersected with the configured categories; unselected categories do not invoke their native producers, and Wolf runs only when injection is selected.

pub fn scan_with_control(
    &mut self,
    text: &str,
    categories: &[SecurityCategory],
    control: &crate::ScanControl,
) -> Result<ScanReport, ScanError>;

[Self::scan_categories] under a shared cancellation/deadline budget.

pub fn shell_verdict(
    &self,
    command: &str,
    context: Option<&ShellContext>,
    prior_facts: &[Facts],
) -> Result<ShellVerdict, ScanError>;

Cat's patronus.verdict/1 for one shell command, which is never executed. context is the harness context (cwd, home, repo root); prior_facts are the verdict.facts of earlier commands of the same session, kept by the caller. A Cat policy is the rule cat.<policy id>: the rules gates of the config turn it off. Text scans do not run Cat.

Shared Native Engine

pub struct NativeProducerOutcome {
    pub detection: NativeDetection,
    pub duration_ms: f64,
}

Raw producer output; result/decision mapping remains the host's responsibility.

pub struct NativeEngine {
    groups: [Vec<NativeProducerSpec>; 3],
}

Owns each selected category's detector state once, without worker threads.

pub fn new(categories: &[SecurityCategory]) -> Self;

Initialize only configured native categories; other categories have no native producers. An empty selection creates no pipelines.

pub fn producers(&self, category: SecurityCategory) -> &[NativeProducerSpec];

Producers in the established category order, or empty for an unselected or non-native category.

pub fn run_producer(
    &self,
    producer: &NativeProducerSpec,
    prepared: &NativeText<'_>,
    gates: &NativeGates,
    control: &ScanControl,
) -> Result<NativeProducerOutcome, ScanError>;

Execute an active producer. Call producer.enabled(gates) before this method. Cancellation is checked before and after detection; panics become detector errors.

Native Policy

pub enum ScoreMode {
    /// Rule acceptance only; every finding scores `1.0`.
    #[default]
    Strict,
    /// Model scores; candidates below `0.50` are dropped.
    Balanced,
    /// Model scores; candidates below `0.30` are dropped.
    Recall,
}

Output mode of the scored native detectors (PII and DLP). Strict is the default and the pre-score behaviour.

pub fn default_rule_enabled(rule_id: &str) -> bool;

Default of a rule without an explicit gate, shared by every host: all non-DLP rules (Cat's shell policies included) except the bare PII forms (opt-in), the DLP credential/secret rules and the classification markings are on, the other DLP content rules are opt-in.

pub struct NativeGates {
    /// Per-rule overrides keyed by stable public rule id.
    pub rules: HashMap<String, bool>,
    /// Per-model or per-native-scanner overrides keyed by result model names
    /// such as `native:mcp_runtime_risk`.
    pub models: HashMap<String, bool>,
    /// Native PII output mode.
    pub pii_mode: ScoreMode,
    /// Native DLP output mode.
    pub dlp_mode: ScoreMode,
    /// Include bounded diagnostic anchor metadata. Disabled by default.
    pub explain: bool,
}

Per-call native policy: rule, model, mode and diagnostics gates, shared by the Core scanner and the full gateway. Missing rule entries use [default_rule_enabled], missing model entries are enabled.

pub fn all_enabled() -> Self;

Gates with every native rule enabled, including the opt-in DLP content families and the bare PII forms.

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

Whether a model or native producer id is enabled.

pub fn allows_rule(&self, id: &str) -> bool;

Whether a stable rule id is enabled.

Native Producer Descriptors

pub struct NativeProducerSpec {
    category: SecurityCategory,
    id: &'static str,
    parent: Option<&'static str>,
    rule: Option<&'static str>,
    detect: Detect,
}

An opaque producer and its shared outer gates. Pipeline state lives with the spec.

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

No public documentation is available yet.

pub fn category(&self) -> SecurityCategory;

No public documentation is available yet.

pub fn enabled(&self, gates: &NativeGates) -> bool;

Parent/model/required-rule gates, independent of host level or conditional gates.

Wolf Execution Options

pub struct WolfExecutionOptions {
    /// Maximum sequence length, including BOS and EOS.
    pub window_tokens: usize,
    /// Content tokens retained between adjacent windows.
    pub overlap_tokens: usize,
    /// Maximum windows in a single ONNX call (not concurrent requests).
    pub batch_size: usize,
}

Wolf document execution. Sizes count tokens, batches count document windows. The defaults preserve the existing 254-content-token inference profile.

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

No public documentation is available yet.

Core ONNX Classification

pub struct OnnxTextClassifier {
    tokenizer: RuntimeTokenizer,
    session: Session,
    input_names: Vec<String>,
    class_names: Vec<String>,
    max_len: usize,
    model_name: String,
    model_path: PathBuf,
    precision: String,
    execution_provider: String,
}

No public documentation is available yet.

pub fn from_dir<P: AsRef<Path>>(
    dir: P,
    class_names: Vec<String>,
    model_name: impl Into<String>,
) -> Result<Option<Self>, Box<dyn std::error::Error>>;

No public documentation is available yet.

pub fn from_dir_with_paths<P: AsRef<Path>>(
    dir: P,
    class_names: Vec<String>,
    model_name: impl Into<String>,
    onnx_candidates: &[&str],
    tokenizer_path: &str,
    max_len: usize,
    backend: ExecutionBackend,
    options: OnnxRuntimeOptions,
) -> Result<Option<Self>, Box<dyn std::error::Error>>;

No public documentation is available yet.

pub fn infer(&mut self, text: &str) -> Result<EvaluationResult, Box<dyn std::error::Error>>;

No public documentation is available yet.

pub fn infer_batch(
    &mut self,
    texts: &[String],
) -> Result<Vec<EvaluationResult>, Box<dyn std::error::Error>>;

No public documentation is available yet.

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

No public documentation is available yet.

pub fn model_path(&self) -> &Path;

No public documentation is available yet.

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

No public documentation is available yet.

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

No public documentation is available yet.

pub fn try_decode(
    &self,
    class_names: &[String],
) -> Result<EvaluationResult, Box<dyn std::error::Error>>;

Checked decoding for manually constructed logits; existing methods remain available.

pub fn try_probabilities(&self) -> Result<Vec<f32>, Box<dyn std::error::Error>>;

No public documentation is available yet.

Core Asset Preparation And Warmup

pub fn wolf_files(precision: crate::wolf::WolfPrecision) -> &'static [&'static str];

Required files for an official export, also used by Ark's category preparation.

pub enum DownloadPolicy {
    #[default]
    Never,
    Missing,
}

No public documentation is available yet.

pub struct WarmupOptions {
    pub download: DownloadPolicy,
    /// Budget for asset lock waiting, downloads and retries; not model construction.
    pub download_timeout_ms: u64,
}

No public documentation is available yet.

pub fn warmup(config: ScannerConfig, options: WarmupOptions) -> Result<Self, ScanError>;

Prepare configured assets, then construct one warm scanner used by subsequent scans.

pub fn warmup_with_wolf_options(
    config: ScannerConfig,
    options: WarmupOptions,
    execution: crate::WolfExecutionOptions,
) -> Result<Self, ScanError>;

Prepare assets and warm one reusable scanner with explicit Wolf execution options.

pub fn prepare_assets(config: &ScannerConfig, options: &WarmupOptions) -> Result<(), ScanError>;

Prepare model files without creating a tokenizer, ONNX session or scanner.

pub fn prepare_shell_assets(
    config: &crate::detectors::shell::ShellConfig,
    options: &WarmupOptions,
) -> Result<(), ScanError>;

Fetch the pinned Cat release into config.bundle_dir unless it already holds a bundle. Files are verified when the scanner loads them.

pub fn prepare_wolf_assets(
    config: &crate::wolf::WolfConfig,
    options: &WarmupOptions,
) -> Result<(), ScanError>;

No public documentation is available yet.

pub fn prepare_wolf_assets_with_progress(
    config: &crate::wolf::WolfConfig,
    options: &WarmupOptions,
    progress: Option<&(dyn Fn(usize, usize) + Send + Sync)>,
) -> Result<(), ScanError>;

No public documentation is available yet.

Core Asset Cache

pub fn wolf_assets_present(dir: &Path, precision: WolfPrecision) -> Result<bool, ScanError>;

Nonblocking readiness. A cache being prepared, or an unfinished managed cache, is not ready.

pub fn prepare_wolf_cache(
    dir: &Path,
    precision: WolfPrecision,
    options: &WarmupOptions,
    progress: Option<&(dyn Fn(usize, usize) + Send + Sync)>,
) -> Result<(), ScanError>;

Prepare a cache without constructing a decision policy, tokenizer or ONNX session.

Core Cancellation And Deadlines

pub struct ScanControl(Arc<State>);

A cloneable work budget. Cancellation also signals any registered native model run. Checkpoints stop further work; an ONNX kernel acknowledges termination cooperatively.

pub fn with_timeout(timeout: Duration) -> Result<Self, ScanError>;

No public documentation is available yet.

pub fn deadline(&self) -> Option<Instant>;

No public documentation is available yet.

pub fn cancel(&self);

No public documentation is available yet.

pub fn cancel_deadline(&self);

No public documentation is available yet.

pub fn check(&self) -> Result<(), ScanError>;

No public documentation is available yet.

Shared Native Types

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 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>>,
    /// Chunk-level evidence for the single final document decision.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub chunk_evidence: Option<serde_json::Value>,
}

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 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,
    /// Risk scoring for shell commands and scripts (POSIX, PowerShell, CMD).
    ShellCommand,
}

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.

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.

pub struct NativeResult {
    /// 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>,
    /// Exact entity evidence returned by span-producing pipelines.
    pub evidence_spans: Vec<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 enum ExecutionBackend {
    /// Keep conservative CPU defaults unless a caller overrides execution mode.
    #[default]
    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.
    #[serde(rename = "coreml", alias = "core_ml")]
    CoreMl,
    /// CUDA execution provider.
    Cuda,
    /// DirectML execution provider.
    DirectMl,
    /// TensorRT execution provider.
    #[serde(rename = "tensorrt", alias = "tensor_rt")]
    TensorRt,
}

Runtime backend profile used to choose default L3 execution behavior.

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.

Wolf Defender Runtime

pub enum WolfPrecision {
    #[default]
    Auto,
    Fp16,
    Int8Int4,
}

No public documentation is available yet.

pub struct WolfConfig {
    pub bundle_dir: PathBuf,
    pub threshold: f64,
    #[serde(default)]
    pub precision: WolfPrecision,
    #[serde(default)]
    pub backend: crate::ExecutionBackend,
    #[serde(default)]
    pub runtime_options: crate::OnnxRuntimeOptions,
}

No public documentation is available yet.

pub struct BundleFile {
    pub path: String,
    pub blake3: String,
}

No public documentation is available yet.

pub enum LogitOutput {
    Scalar,
    BinaryMargin,
}

No public documentation is available yet.

pub struct ParityCase {
    #[serde(default)]
    pub text: Option<String>,
    pub token_ids: Vec<u32>,
    pub expected_logit: f64,
}

No public documentation is available yet.

pub struct DocumentCase {
    pub text: String,
    pub expected_logit: f64,
    pub windows: u64,
}

No public documentation is available yet.

pub struct WolfManifest {
    pub schema_version: u32,
    pub model_id: String,
    pub revision: String,
    pub precision: String,
    pub model: BundleFile,
    pub tokenizer: BundleFile,
    pub output_name: String,
    pub output: LogitOutput,
    pub content_tokens: usize,
    pub sequence_tokens: usize,
    #[serde(default)]
    pub dynamic_sequence: bool,
    pub pad_id: u32,
    pub reference: String,
    pub parity_cases: Vec<ParityCase>,
    #[serde(default)]
    pub document_cases: Vec<DocumentCase>,
    pub logit_tolerance: f64,
    #[serde(default)]
    pub relative_tolerance: f64,
    #[serde(default = "default_probability_tolerance")]
    pub probability_tolerance: f64,
}

An export contract produced alongside a training-verified FP16 export.

pub struct WolfResult {
    pub document_logit: f64,
    pub attack_probability: f64,
    pub threshold: f64,
    pub matched: bool,
    pub windows: u64,
    pub model_id: String,
    pub revision: String,
    pub precision: String,
}

No public documentation is available yet.

pub struct WolfProgress {
    pub windows: u64,
    pub total_windows: u64,
    /// Absent before the first inference; otherwise the running SmoothMax logit.
    pub document_logit: Option<f64>,
}

Non-authoritative progress over the windows processed so far.

pub struct WolfRunner {
    session: Session,
    tokenizer: Arc<MmbertPairTokenizer>,
    manifest: WolfManifest,
    threshold: f64,
    model_path: PathBuf,
    execution_provider: String,
    options: WolfExecutionOptions,
    fixed_width: Option<usize>,
}

No public documentation is available yet.

pub fn new(config: &WolfConfig) -> Result<Self, ScanError>;

No public documentation is available yet.

pub fn new_with_options(
    config: &WolfConfig,
    options: WolfExecutionOptions,
) -> Result<Self, ScanError>;

Construct and warm a runner; execution sizes are validated against the local export.

pub fn set_threshold(&mut self, threshold: f64) -> Result<(), ScanError>;

Change the decision threshold without loading or warming another session.

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

No public documentation is available yet.

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

No public documentation is available yet.

pub fn model_path(&self) -> &Path;

No public documentation is available yet.

pub fn scan(&mut self, text: &str) -> Result<WolfResult, ScanError>;

No public documentation is available yet.

pub fn scan_with_control(
    &mut self,
    text: &str,
    control: &ScanControl,
) -> Result<WolfResult, ScanError>;

Scan with cooperative cancellation and termination of active ONNX runs.

pub fn scan_with_progress(
    &mut self,
    text: &str,
    progress: &mut dyn FnMut(WolfProgress),
) -> Result<WolfResult, ScanError>;

Emit a start update and one update per window without retaining chunk outputs. Counting tokens first provides exact totals and uses bounded tokenizer memory.

pub fn scan_with_progress_and_control(
    &mut self,
    text: &str,
    control: &ScanControl,
    progress: &mut dyn FnMut(WolfProgress),
) -> Result<WolfResult, ScanError>;

No public documentation is available yet.

pub fn execution_options(&self) -> WolfExecutionOptions;

The effective window and batch configuration of this reusable session.

pub fn new(bundle_dir: impl Into<PathBuf>, threshold: f64) -> Self;

No public documentation is available yet.

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 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 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 L2 package entry for a public model name.

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

Check whether an official NTDB L2 package cache matches its pinned revision.

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 shell_command_assets_present(target_dir: &Path) -> bool;

Check whether the complete revision-pinned shell_command model is cached.

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

Download the revision-pinned shell_command risk model 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 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 v4 package manifest.