Domain Plugins

Core Vajra is domain-agnostic. It analyzes structure, statistics, and deviation from norms — without knowing what the data represents. Domain intelligence enters through plugins that extend the engine without contaminating it.

A plugin does not change what Vajra computes. It enriches what Vajra knows.

The Plugin Architecture

Plugins contribute four kinds of extensions:

1. Type recognizers — pattern matchers that identify domain-specific value types (ICD-10 codes, NPIs, SWIFT codes)
2. Concern profiles — custom scoring weight vectors and rendering templates
3. Relationship hints — domain knowledge about which fields form logical groups
4. Custom renderers — domain-specific essence rendering templates

Plugins cannot modify the core analysis pipeline, access the filesystem beyond their own configuration, make network calls, or mutate the input document. They are additive. They are isolated.

The VajraPlugin Trait

#![allow(unused)]
fn main() {
pub trait VajraPlugin: Send + Sync {
    /// Plugin identifier.
    fn name(&self) -> &str;

    /// Plugin version string.
    fn version(&self) -> &str;

    /// Additional type recognizers beyond the core DFA bank.
    /// These run alongside the core recognizers during semantic lifting.
    fn type_recognizers(&self) -> Vec<Box<dyn TypeRecognizer>> {
        vec![]
    }

    /// Additional concern profile definitions.
    /// These appear alongside built-in profiles in `vajra profiles`.
    fn concern_profiles(&self) -> Vec<Box<dyn ConcernProfile>> {
        vec![]
    }

    /// Field relationship heuristics.
    /// Example: "code + description + system = coded concept"
    fn relationship_hints(&self) -> Vec<RelationshipHint> {
        vec![]
    }

    /// Custom rendering templates for essence output.
    fn renderers(&self) -> Vec<Box<dyn EssenceRenderer>> {
        vec![]
    }
}
}

Every method has a default implementation that returns empty. A plugin can implement only the capabilities it needs.

TypeRecognizer

Type recognizers extend Vajra’s semantic lifting layer. They match raw string values against domain-specific patterns.

#![allow(unused)]
fn main() {
pub trait TypeRecognizer: Send + Sync {
    /// The name of the recognized type (e.g., "ICD-10-CM", "CPT", "NPI").
    fn type_name(&self) -> &str;

    /// Returns true if the value matches this type's pattern.
    fn matches(&self, value: &str) -> bool;

    /// Optional confidence level for the match.
    fn confidence(&self, value: &str) -> f64 {
        if self.matches(value) { 1.0 } else { 0.0 }
    }
}
}

Type recognizers run during Layer 4 (Semantic Lifting) of the engine pipeline. They are evaluated after the core DFA bank, allowing domain-specific patterns to augment — not override — the core type inference.

RelationshipHint

Relationship hints tell Vajra that certain field combinations form logical groups:

#![allow(unused)]
fn main() {
pub struct RelationshipHint {
    /// Fields that form a logical group when co-located.
    pub field_patterns: Vec<String>,

    /// Name for this relationship.
    pub name: String,

    /// Description of what the group represents.
    pub description: String,
}
}

Example from the medical plugin:

#![allow(unused)]
fn main() {
RelationshipHint {
    field_patterns: vec![
        "code".to_string(),
        "system".to_string(),
        "display".to_string(),
    ],
    name: "coded-concept".to_string(),
    description: "A coded value with its coding system and human-readable display".to_string(),
}
}

When Vajra finds code, system, and display as sibling keys in an object, the medical plugin’s relationship hint identifies this as a coded concept — not three independent strings.

The Medical Plugin: vajra-domain-med

The medical plugin is the reference implementation. It demonstrates every plugin capability.

Type Recognizers

Relationship Hints

What It Enables

With the medical plugin loaded, vajra inspect on a medical claim produces:

=== Domain Type Recognition ===
  $.claims[*].diagnosis[*].code           E11.9      ICD-10-CM
  $.claims[*].diagnosis[*].code           J44.1      ICD-10-CM
  $.claims[*].service_lines[*].procedure_code  99213  CPT
  $.claims[*].provider.npi                1234567890 NPI
  $.claims[*].service_lines[*].adjustment.reason  CO-45  Denial Reason

Without the plugin, those values are just strings. With it, they are clinically meaningful codes.

Building Your Own Plugin

Step 1: Create a Crate

cargo new vajra-domain-finance --lib

Step 2: Depend on vajra-types

# Cargo.toml
[dependencies]
vajra-types = { version = "0.1", path = "../vajra-types" }

Step 3: Implement the Trait

#![allow(unused)]
fn main() {
use vajra_types::traits::{VajraPlugin, TypeRecognizer, RelationshipHint};

pub struct FinancePlugin;

impl VajraPlugin for FinancePlugin {
    fn name(&self) -> &str { "finance" }
    fn version(&self) -> &str { "0.1.0" }

    fn type_recognizers(&self) -> Vec<Box<dyn TypeRecognizer>> {
        vec![
            Box::new(SwiftCodeRecognizer),
            Box::new(IbanRecognizer),
            Box::new(CurrencyCodeRecognizer),
        ]
    }

    fn relationship_hints(&self) -> Vec<RelationshipHint> {
        vec![
            RelationshipHint {
                field_patterns: vec![
                    "amount".to_string(),
                    "currency".to_string(),
                ],
                name: "monetary-value".to_string(),
                description: "Amount with its currency denomination".to_string(),
            },
        ]
    }
}

struct SwiftCodeRecognizer;

impl TypeRecognizer for SwiftCodeRecognizer {
    fn type_name(&self) -> &str { "SWIFT/BIC" }

    fn matches(&self, value: &str) -> bool {
        let len = value.len();
        (len == 8 || len == 11)
            && value[..4].chars().all(|c| c.is_ascii_uppercase())
            && value[4..6].chars().all(|c| c.is_ascii_uppercase())
            && value[6..8].chars().all(|c| c.is_ascii_alphanumeric())
    }
}
}

Step 4: Register the Plugin

Static plugins are compiled into the binary at build time by adding the crate to vajra-cli’s dependencies.

Dynamic plugins are loaded at runtime via libloading from the plugin directory (default: ~/.vajra/plugins/).

Error Isolation

Plugins run in an isolation boundary. If a plugin panics or returns an error:

1. The panic is caught at the plugin boundary (via std::panic::catch_unwind).
2. Core analysis continues without the plugin’s contributions.
3. The plugin failure is recorded in the output’s provenance metadata.
4. A diagnostic message is emitted to stderr.

vajra: plugin "finance" failed during type recognition: index out of bounds
vajra: continuing analysis without finance plugin contributions

No plugin failure can crash Vajra. No plugin can corrupt the core analysis. The isolation is structural, not aspirational.

Plugin Constraints

A plugin may:

• Register type recognizers, profiles, relationship hints, and renderers
• Read its own configuration files
• Use any safe Rust code internally

A plugin may not:

• Modify the core analysis pipeline
• Access the filesystem beyond its own config directory
• Make network calls
• Mutate the input document
• Introduce nondeterminism (all plugin methods must be deterministic)

Shipped Plugins

Six domain plugins ship with Vajra, all enabled by default via feature flags:

Feature Flags

# vajra-cli/Cargo.toml
[features]
default = ["medical", "security", "devops", "source", "encoding", "github"]
medical = ["vajra-domain-med"]
security = ["vajra-domain-sec"]
devops = ["vajra-domain-devops"]
source = ["vajra-source", "vajra-domain-source"]
encoding = ["vajra-domain-encoding"]
github = ["vajra-domain-github"]
all-plugins = ["medical", "security", "devops", "source", "encoding", "github"]

Build without a plugin: cargo build --no-default-features --features security,devops

The Security Plugin: vajra-domain-sec

The security plugin recognizes types commonly found in SIEM events, vulnerability scans, threat intelligence feeds, and network flow data.

Type Recognizers

The DevOps Plugin: vajra-domain-devops

The DevOps plugin recognizes types in Kubernetes manifests, Terraform state, CI/CD pipeline output, Docker configurations, and cloud infrastructure JSON.

Type Recognizers

The Source Code Plugin: vajra-domain-source

The source code plugin recognizes patterns in the JSON trees produced by vajra-source (tree-sitter CST-to-JSON output). It works alongside vajra-source, which handles the parsing.

Type Recognizers

Relationship Hints

The Encoding Plugin: vajra-domain-encoding

The encoding plugin detects data encodings embedded in JSON string values. It identifies Base64, hex, URL encoding, HTML entities, PEM certificates, and more — including adversarial patterns like double encoding and mixed encoding used for evasion.

Type Recognizers (3 Tiers)

Tier 1 — Definite confidence (structural markers, near-zero false positives):

Tier 2 — Dominant confidence (strong patterns, low false positives):

Tier 3 — Heuristic (aggressive false positive gating):

Layer Peeling API

Beyond type recognition, the plugin provides detect_encoding_layers() for recursive analysis:

#![allow(unused)]
fn main() {
use vajra_domain_encoding::detect_encoding_layers;

let layers = detect_encoding_layers("%2548ello%2520world", 5);
// Returns: [url_encoded(depth=0), url_encoded(depth=1)]
}

Bounded at depth 5, decode capped at 4KB per layer. Catches base64(url(hex(payload))).

The GitHub Plugin: vajra-domain-github

The GitHub plugin recognizes types commonly found in GitHub API responses, webhook payloads, and exported repository data (PRs, issues, commits, reviews, releases, workflow runs).

Type Recognizers

Relationship Hints

Future Plugin Domains

The architecture supports any domain: