🛡️ The Master Guide to AI Guardrails & Custom Validators (DSOM Protocol)

Document Type: Sovereign Master Architecture & Implementation Blueprint
Target Audience: Systems Architects, AI Security Engineers, DevOps/GitOps Practitioners, and Cognitive Twin Agents
Status: Production Reference Standard | OKF v0.2 Compliant
Live URL: https://linuxmalaysia.github.io/deep-state-of-mind-for-my-ai/governance/AI-GUARDRAILS-MASTER-GUIDE/

---

🧭 1. Executive Summary & The Problem Space

As autonomous AI agents are entrusted with mission-critical systems engineering, IT infrastructure automation, and software engineering tasks, unconstrained LLM execution poses catastrophic failure modes:

1. Hallucinated & Destructive Terminal Invocations: Agents running exploratory commands, wiping directories, or modifying system configuration files without prior context.
2. Context Window Flooding & Runaway Token Spend: Uncapped commands spewing megabytes of logs directly into prompt context, triggering severe context decay and financial waste.
3. Sensitive Credential & PII Leakage: Accidental leakage of GitHub tokens, SSH private keys, AWS secrets, or database credentials into Git tracking or public web outputs.
4. Knowledge Degradation & Formatting Corruption: Corruption of repository knowledge graphs via invalid YAML frontmatter, Byte Order Marks (BOMs), or unstructured markdown outputs.

The Deep State of Mind (DSOM) framework solves these challenges through a unified, defense-in-depth guardrails architecture. This document serves as the single definitive master reference for understanding, configuring, and developing custom validators within DSOM.

---

🏛️ 2. The Tri-Phasic Guardrail Interception Pipeline

In DSOM, guardrails are not monolithic wrappers; they are stratified across the Tri-Phasic Mind model to intercept actions at the exact point of execution:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                          TRI-PHASIC GUARDRAIL INTERCEPTION                             │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ 🌤️ ACTIVE STATE     │ FastMCP Input / Output Interceptors                             │
│                      │ Intercepts tool calls before terminal or disk modification.    │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ 🌗 TWILIGHT STATE   │ Inline AST, Regex, Linter & Token Gates                         │
│                      │ Evaluates code syntax, strips UTF-8 BOM, caps token windows.   │
├────────────────────────────────────────────────────────────────────────────────────────┤
│ 🌙 DEEP STATE       │ EOD Palace-Sync, Pytest Suite & GitOps Verification Gates       │
│                      │ Validates entire corpus integrity prior to multi-remote push.  │
└────────────────────────────────────────────────────────────────────────────────────────┘

i) Active State: FastMCP Tool Guardrails (Input & Output Filtering)

• Execution Layer: tools/mcp/server.py and direct IDE interfaces (Cursor, Claude Desktop, Google Antigravity).
• Mechanism: Every MCP tool invocation executes pre-call argument validation and post-call output sanitization. If an argument contains unvetted tokens or unsafe paths, execution is immediately blocked before touching the OS.

ii) Twilight State: Inline AST, Regex & Token Interceptors (The Continuous Subconscious)

• Execution Layer: Background execution loops, dsom-token-calculator, and pre-commit hooks.
• Mechanism: Continuously checks memory files and generated scripts. Enforces byte-capped executions (Rule 10), strips leading UTF-8 BOMs, and ensures uv execution isolation (Rule 16).

iii) Deep State: The Cognitive Verification Harness (The EOD Gate)

• Execution Layer: playbooks/dsom/eod-palace.yml, tools/hibernation.ps1, tools/eod-palace.ps1, and tests/.
• Mechanism: Before any commit is pushed to remote repositories (GitHub and GitLab), the full pytest test harness executes. Zero unvalidated changes or formatting corruptions are allowed to persist into historical ledgers.

---

⚖️ 3. Dual-Path Architecture: Guardrails AI vs. DSOM Native

To maximize versatility across diverse enterprise environments, DSOM codifies Rule 29 (Dual-Path Custom Validator Architecture Mandate), supporting two complementary execution paradigms:

                                 ┌───────────────────────────────┐
                                 │   AI AGENT TASK INVOCATION    │
                                 └──────────────┬────────────────┘
                                                │
                       Is the task an external LLM API call or internal GitOps?
                                                │
                     ┌──────────────────────────┴──────────────────────────┐
                     ▼                                                     ▼
      ┌─────────────────────────────┐                       ┌─────────────────────────────┐
      │   GUARDRAILS AI FRAMEWORK   │                       │    DSOM NATIVE LIGHTWEIGHT  │
      │          (Path A)           │                       │          (Path B)           │
      ├─────────────────────────────┤                       ├─────────────────────────────┤
      │ • External LLM app gateways │                       │ • Local GitOps & MCP tools  │
      │ • Pydantic JSON schemas     │                       │ • Pure Python AST & Regex   │
      │ • Off-the-shelf Hub models  │                       │ • Zero external dependencies│
      │ • OpenAI/Anthropic pipelines│                       │ • <0.5ms execution latency  │
      └─────────────────────────────┘                       └─────────────────────────────┘

Detailed Comparative Matrix:

Dimension / Metric	📦 Path A: Guardrails AI Framework	⚡ Path B: DSOM Native Lightweight Implementation
Primary Scope	Web applications, external chatbot gateways, structured API JSON output.	Local repository hygiene, FastMCP servers, OS command interception, CLI tools.
Dependencies	Requires guardrails-ai, pydantic (v2), and optional ML models.	Standard Library only (re, ast, dataclasses, typing), executed via uv.
Execution Latency	~5–25ms per validation loop.	<0.5ms (instantaneous in-memory inspection).
On-Fail Actions	reask (re-prompts LLM), fix (programmatic patch), filter, refrain, exception.	fix (in-memory fix), block (raises error), reask (via episodic anchor rollbacks).
Network Dependency	May require external API access or local hub package downloads.	100% Offline / Air-Gapped Capable.
Memory Footprint	~80–120MB Python virtual environment size.	Zero additional memory footprint.

---

📦 4. Implementation Path A: Guardrails AI Framework (How-To Guide)

When building public-facing AI applications, API pipelines, or validating Pydantic schemas, use the official Guardrails AI framework.

Step 1: Environment Setup via uv

uv add guardrails-ai

Step 2: Define the Custom Validator

Custom validators in Guardrails AI inherit from Validator and use the @register_validator decorator:

"""
tools/validators/guardrails_ai_okf_validator.py
Guardrails AI Custom Validator for OKF & BOM Verification
"""

from typing import Any, Dict, Optional
from guardrails.validators import (
    FailResult,
    PassResult,
    ValidationResult,
    Validator,
    register_validator,
)

@register_validator(name="dsom/okf_frontmatter_validator", data_type="string")
class GuardrailsOKFValidator(Validator):
    """
    Validates that text begins with valid OKF YAML frontmatter
    and automatically strips leading UTF-8 BOM characters.
    """

    def __init__(self, on_fail: str = "fix", **kwargs):
        super().__init__(on_fail=on_fail, **kwargs)

    def validate(self, value: Any, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        text = str(value)

        # Check 1: Strip BOM
        if text.startswith("\ufeff"):
            fixed = text.lstrip("\ufeff")
            return FailResult(
                error_message="Leading UTF-8 BOM detected.",
                fix_value=fixed,
            )

        # Check 2: Verify frontmatter fence
        if not (text.startswith("---\n") or text.startswith("---\r\n")):
            return FailResult(
                error_message="Document must start with OKF frontmatter fence ('---')."
            )

        return PassResult()

Step 3: Instantiate Guard & Validate LLM Output

from guardrails import Guard
from tools.validators.guardrails_ai_okf_validator import GuardrailsOKFValidator

# Create a Guard instance with on_fail='fix'
guard = Guard().use(GuardrailsOKFValidator(on_fail="fix"))

raw_llm_response = "\ufeff---\nokf_version: 0.2\ntitle: Example\n---\n# Content"
outcome = guard.validate(raw_llm_response)

print("Validated Output:\n", outcome.validated_output)

---

⚡ 5. Implementation Path B: DSOM Native Lightweight Implementation

For internal repository automation, FastMCP servers, and CLI workflows, use DSOM's zero-dependency pure Python framework.

Core Validator Base Class (tools/validators/base.py):

"""
tools/validators/base.py
DSOM Native Lightweight Validator Base Class
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Any, Dict, Optional, Literal

@dataclass
class ValidationResult:
    is_valid: bool
    corrected_value: Optional[Any] = None
    error_message: Optional[str] = None
    action_taken: Literal["pass", "fixed", "blocked", "reask"] = "pass"

class BaseDSOMValidator(ABC):
    """Abstract Base Class for all DSOM Native Validators."""

    name: str = "base_validator"
    on_fail: Literal["fix", "block", "reask"] = "block"

    @abstractmethod
    def validate(self, value: Any, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        """Evaluate value and return a deterministic ValidationResult."""
        pass

Native Validator 1: Credential & PII Leak Guardian (tools/validators/credential_guardian.py)

Implements Rule 24 (Defensive Credential Handling) to intercept API tokens and private keys before they touch disk or Git:

"""
tools/validators/credential_guardian.py
Interception guardrail for secrets and credentials.
"""

import re
from typing import Any, Dict, Optional
from tools.validators.base import BaseDSOMValidator, ValidationResult

class CredentialGuardianValidator(BaseDSOMValidator):
    name = "credential_guardian"
    on_fail = "block"

    PATTERNS = [
        re.compile(r"ghp_[a-zA-Z0-9]{36}"),                       # GitHub Classic PAT
        re.compile(r"github_pat_[a-zA-Z0-9_]{82}"),               # GitHub Fine-grained PAT
        re.compile(r"glpat-[a-zA-Z0-9\-]{20}"),                   # GitLab PAT
        re.compile(r"-----BEGIN (RSA|OPENSSH|EC) PRIVATE KEY-----"), # Private Keys
        re.compile(r"AKIA[0-9A-Z]{16}"),                          # AWS Access Key
    ]

    def validate(self, text: str, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        for pattern in self.PATTERNS:
            if pattern.search(text):
                return ValidationResult(
                    is_valid=False,
                    error_message=f"Credential leak detected matching security pattern: {pattern.pattern}",
                    action_taken="blocked"
                )
        return ValidationResult(is_valid=True)

Native Validator 2: Python AST UV-Execution Gatekeeper (tools/validators/ast_uv_gatekeeper.py)

Implements Rule 16 (The uv Mandate) by inspecting shell strings to block raw pip or unmanaged python calls:

"""
tools/validators/ast_uv_gatekeeper.py
AST/Command gatekeeper enforcing isolated Python execution.
"""

from typing import Any, Dict, Optional
from tools.validators.base import BaseDSOMValidator, ValidationResult

class PythonExecutionValidator(BaseDSOMValidator):
    name = "python_execution_gatekeeper"
    on_fail = "block"

    PROHIBITED_COMMANDS = ["pip install", "python3 ", "python "]

    def validate(self, command: str, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        trimmed = command.strip()

        # Block raw pip
        if trimmed.startswith("pip ") or " pip install " in trimmed:
            return ValidationResult(
                is_valid=False,
                error_message="Violation of Rule 16: Raw pip prohibited. Use 'uv add' or 'uv run --with'.",
                action_taken="blocked"
            )

        return ValidationResult(is_valid=True)

Native Validator 3: OKF v0.2 Frontmatter & Trust Signal Auditor (tools/validators/okf_v02_validator.py)

Implements Rule 2 and Rule 6, ensuring all modified documents carry complete trust signals:

"""
tools/validators/okf_v02_validator.py
Validates OKF v0.2 YAML frontmatter and provenance fields.
"""

import yaml
from typing import Any, Dict, Optional
from tools.validators.base import BaseDSOMValidator, ValidationResult

class OKFv02Validator(BaseDSOMValidator):
    name = "okf_v02_validator"
    on_fail = "fix"

    REQUIRED_V02_FIELDS = ["okf_version", "type", "title", "timestamp", "topics", "sources", "generated", "verified", "status", "stale_after"]

    def validate(self, markdown_content: str, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        if not markdown_content.startswith("---"):
            return ValidationResult(is_valid=False, error_message="Missing YAML frontmatter fence.", action_taken="blocked")

        try:
            parts = markdown_content.split("---", 2)
            header_yaml = parts[1]
            data = yaml.safe_load(header_yaml)

            if data.get("okf_version") == 0.2:
                missing = [f for f in self.REQUIRED_V02_FIELDS if f not in data]
                if missing:
                    return ValidationResult(
                        is_valid=False,
                        error_message=f"OKF v0.2 document missing trust fields: {missing}",
                        action_taken="blocked"
                    )
            return ValidationResult(is_valid=True)
        except Exception as e:
            return ValidationResult(is_valid=False, error_message=f"YAML parse error: {str(e)}", action_taken="blocked")

---

🔌 6. Integration with the Native FastMCP Server (tools/mcp/server.py)

Guardrails custom validators are hooked directly into our native Model Context Protocol (FastMCP) server. This ensures that any AI IDE (Cursor, Claude Desktop, VSCode) connecting to DSOM is subject to deterministic guardrails before executing tools:

"""
Snippet: tools/mcp/server.py with Inline Guardrail Interceptors
"""

from fastmcp import FastMCP
from tools.validators.credential_guardian import CredentialGuardianValidator
from tools.validators.okf_v02_validator import OKFv02Validator

mcp = FastMCP("DSOM Sovereign MCP Server")
credential_guardian = CredentialGuardianValidator()
okf_validator = OKFv02Validator()

@mcp.tool()
def write_sovereign_knowledge(file_path: str, markdown_content: str) -> str:
    """Safely writes markdown knowledge to the Palace with strict guardrail evaluation."""

    # 1. Evaluate Credential Guardian
    cred_res = credential_guardian.validate(markdown_content)
    if not cred_res.is_valid:
        raise ValueError(f"[GUARDRAIL VIOLATION: CREDENTIAL LEAK] {cred_res.error_message}")

    # 2. Evaluate OKF Frontmatter Integrity
    okf_res = okf_validator.validate(markdown_content)
    if not okf_res.is_valid:
        raise ValueError(f"[GUARDRAIL VIOLATION: OKF SCHEMA] {okf_res.error_message}")

    # 3. Perform atomic write
    # ... os.replace() write logic ...
    return f"Successfully validated and written to {file_path}"

---

📋 7. Summary of All Related Guardrail Documents

For human operators and AI agents seeking specialized details on specific guardrail subsystems:

Document	Focus Area	Local File Link
Custom Validators Guide	Step-by-step implementation guide for building custom validator classes.	docs/governance/DSOM-CUSTOM-VALIDATORS-GUIDE.md
The Tri-Phasic Mind	Deep architectural theory on Subsystem 4 (Metacognition & Guardrails).	docs/governance/DSOM-TRI-PHASIC-COGNITIVE-ARCHITECTURE.md
Byte-Capped Executions	Programmatic terminal command size-limiting and token window defense.	docs/governance/BYTE-CAPPED-EXECUTION-FRAMEWORK.md
Knowledge-First Discovery	5-step SOP preventing exploratory command hallucinations.	docs/governance/SOP-KNOWLEDGE-FIRST-DISCOVERY.md
Python UV Environment Guide	Rule 16 isolation mechanics preventing environment pollution.	docs/governance/PYTHON-UV-ENVIRONMENT-GUIDE.md
Core AI Rulebook	Master constitution containing all 29 binding sovereign operational rules.	.agents/AGENTS.md

---

📚 SOURCES

• Guardrails AI Official Documentation: Custom Validators - Primary specification for Pydantic/Hub-based validators.
• DSOM Tri-Phasic Cognitive Architecture - Cognitive states and subsystem 4 guardrail definitions.
• The Core AI Rulebook - Rules 2, 6, 10, 13, 16, 20, 24, 28, and 29.

---

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-22
Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0