Testing \u201cSafe Delete\u201d Protections with Hexarch Guardrails

This guide walks through a simple, practical example for validating \u201csafe delete\u201d protections and understanding how Hexarch Guardrails enforces API control. The goal is to demonstrate how potentially destructive operations can be stopped before they execute, using policy-driven interception rather than post-hoc error handling. The hexarch-guardrails library achieves this by evaluating intent at the function boundary, prior to any database mutation or external API call.

1. How API Control Works

Hexarch Guardrails introduces a pre-flight enforcement step around guarded functions. When the @guardian.check("policy_id") decorator is applied, the following sequence occurs:

Interception happens first. Before the function body executes, the Guardian captures execution context, such as which actor is calling the function and any associated metadata.
Policy evaluation follows. This context is evaluated against the rules defined in hexarch.yaml, using the configured policy engine to determine whether the action is permitted.
Enforcement is immediate. If the policy denies the action, a PolicyViolation exception is raised. Execution stops at that point, preventing the code from reaching an expensive API call, database delete, or irreversible side effect.
Audit logging is automatic. Every decision—allowed or denied—is persisted to the local audit store, creating a durable record of intent, outcome, and reasoning.

This model ensures that safety controls are structural rather than advisory. Code that violates policy simply does not run.

2. Testing the \u201cSafe Delete\u201d Protection

To see this behavior in action, create a small test script. This example assumes a safe_delete policy exists in hexarch.yaml.

Create a new file named test_safety.py in the project directory and add the following code:

from hexarch_guardrails import Guardian
from hexarch_guardrails.exceptions import PolicyViolation

# Initialize the Guardian (automatically loads hexarch.yaml)
guardian = Guardian()

# This function is protected by the "safe_delete" policy
@guardian.check("safe_delete")
def delete_user_records(user_id):
    # In a real application, this would execute a database delete
    print(f"\u2705 SUCCESSFULLY DELETED records for user: {user_id}")

# --- TEST 1: Accidental deletion attempt (expected to fail) ---
print("--- TEST 1: Attempting an accidental delete ---")
try:
    delete_user_records("user_123")
except PolicyViolation as e:
    print(f"\u274c BLOCKED: {e}")

# --- TEST 2: Intentional deletion attempt (expected to pass) ---
print("\n--- TEST 2: Attempting a confirmed delete ---")
# Explicit confirmation is added to the execution context
guarded_delete = guardian.check(
    "safe_delete",
    context={"confirm": True}
)(delete_user_records)

guarded_delete("user_123")

When executed, the first test demonstrates the default safety posture: deletion is blocked because intent was not explicitly confirmed. The second test shows how an intentional, confirmed action is allowed to proceed.

3. Understanding `decisions.db`

The decisions.db file is a local SQLite database that serves as the system\u2019s decision ledger. It functions as a flight recorder for guarded code paths and is often one of the most valuable artifacts in a project that consumes paid APIs or manages sensitive data.

This database contains a record of allowed versus blocked actions, making it easy to see when guardrails prevented unnecessary or dangerous execution. It also stores the rationale behind each decision, such as budget limits, missing confirmations, or policy mismatches. In addition, it captures usage metadata—timestamps, actor identifiers, and policy IDs—which can be used to analyze usage patterns and track operational \u201cburn rate.\u201d

Because this data is local and structured, it can be inspected directly, queried, or exported for reporting and review.

4. Inspecting Guardrail Impact and Cost Savings

Hexarch provides an administrative CLI for reviewing audit data without writing custom queries. To see recent blocked actions, run the following command:

# Show blocked actions from the last 24 hours
hexarch-ctl audit blocked --timeframe 24h

This report highlights where guardrails intervened, making it easier to identify runaway code paths, missing confirmations, or misconfigured automation before they result in additional cost or data loss.

Why This Pattern Matters