nagasatish chilakamarti

Posted on May 3 • Originally published at blogs.tealtiger.ai

TealTiger v1.2: Deterministic Governance for AI Agents — Architecture Deep Dive

#aigovernance #opensource #security #typescript

The Problem

AI agents are moving from answering questions to taking actions — calling APIs, querying databases, executing code, managing memory. The security surface has shifted from "what the model says" to "what the agent does."

Most guardrail solutions address the first problem. They filter content. They detect prompt injection. They moderate output. These are necessary but insufficient.

The gap: who decides what the agent is allowed to do once it's been talked into doing it?

Tool authorization. Memory governance. Cost limits. Audit evidence. These aren't content safety problems — they're governance problems. And they require a different architecture.

What We Built

TealTiger v1.2 is a deterministic governance engine for AI agents. It evaluates every agent action against policy — in parallel, at runtime, with no LLM in the decision path.

The key design constraint: same input + same policy = same decision, every time. No probabilistic scoring. No model inference. Pattern matching, severity ranking, and boolean logic.

This makes every governance decision auditable, reproducible, and testable.

Architecture

Parallel Module Evaluation

v1.2 introduces a module system. Instead of a monolithic policy evaluator, governance is decomposed into independent modules — each owning a single dimension (secrets, memory, reliability, registry).

All modules run in parallel via Promise.allSettled:

Request arrives
    ↓
┌─────────────┬──────────────┬───────────────┬─────────────┐
│ TealSecrets │ TealRegistry │ TealReliability│ TealMemory │
│ (secrets)   │ (allowlist)  │ (circuit brk)  │ (scope)    │
└──────┬──────┴──────┬───────┴───────┬────────┴──────┬──────┘
       └─────────────┼───────────────┘               │
                     ↓                               │
              Merge: most restrictive wins ←─────────┘
                     ↓
              TEEC validation
                     ↓
              Decision returned

The merge strategy is simple: most restrictive action wins. If TealSecrets returns DENY and TealRegistry returns ALLOW, the final decision is DENY. There is no way to "un-deny" a request.

This is the same principle as AWS IAM's "explicit deny overrides allow" — adapted for AI agent governance with 12 graduated actions instead of binary allow/deny.

Action Severity Scale

Severity	Actions
100	`DENY`, `DENY_WRITE`, `DENY_READ`
80	`REQUIRE_APPROVAL`
70	`REDACT`, `REDACT_AND_WRITE`
60	`DEGRADE`, `STORE_SUMMARY_ONLY`
50	`TRANSFORM`
0	`ALLOW`, `ALLOW_WRITE`

Fail-Closed by Default

If any module throws an exception during evaluation, the engine returns DENY. A broken guardrail should not become an open door.

const engine = new TealEngineV12({
  policy: myPolicy,
  modules: [new TealSecrets(), new TealRegistry(), new TealMemory()],
  failurePolicy: { default: 'FAIL_CLOSED' }
});

The 7 Governance Modules

TealSecrets — Secret Detection

Scans content for 500+ secret patterns across 9 categories (API keys, tokens, credentials, certificates, cloud secrets, database strings, messaging webhooks, payment keys, infrastructure secrets). Each finding includes a confidence score and content fingerprint — never the actual secret.

const decision = await engine.evaluateV12(
  { content: 'Deploy with key AKIAIOSFODNN7EXAMPLE...' },
  { correlation_id: 'req-001' }
);
// decision.action === 'DENY'
// decision.findings === [{ type: 'aws_access_key', confidence: 0.95, ... }]

TealRegistry — Model & Tool Allowlisting

Enforces which models and tools an agent can use. If it's not on the list, the agent can't call it. Supports version pinning and provenance verification.

const engine = new TealEngineV12({
  policy: {
    registry: {
      models: ['gpt-4o', 'claude-3-sonnet'],
      tools: ['web_search', 'file_read'],
      strict: true
    }
  },
  modules: [new TealRegistry()]
});

TealReliability — Circuit Breakers & Fallbacks

Retry budgets, circuit breakers (3-state: closed/open/half-open), fallback chains, and degradation policies. Prevents cascading failures and runaway costs.

TealMemory — Memory Governance

Controls what agents can write to and read from memory. 5 scopes (session, agent, user, shared, global) and 4 classification levels (public, internal, confidential, restricted). Introduces 5 new decision actions specific to memory governance.

BundleExporter — Evidence Export

Every decision produces a structured evidence envelope. Export as SARIF v2.1.0 (for security tooling), JUnit XML (for CI/CD), or JSON (for custom pipelines).

GovernanceDashboard & TEECValidationRunner

Governance visualization and evidence contract validation.

TEEC — Typed Evidence & Evidence Contracts

Every governance decision in v1.2 is validated against the TEEC registry:

32 reason codes across 8 categories (policy, content, tool, reliability, cost, mode, secrets, memory)
18 event types for audit trail
12 decision actions with severity-based merge

TEEC makes the evidence contract explicit. Every decision includes a correlation_id, timestamp, reason_codes, event_type, teec_version, and component_versions. This is what makes governance decisions reconstructable after the fact.

Docker Governance Sidecar

Not every agent is written in TypeScript or Python. The governance sidecar wraps TealEngine v1.2 as a language-agnostic HTTP API:

docker pull tealtigeradmin/tealtiger-typescript:1.2-governance
docker run -p 8080:8080 tealtigeradmin/tealtiger-typescript:1.2-governance

Six endpoints:

Method	Path	Purpose
POST	`/evaluate`	Policy evaluation → Decision
POST	`/validate`	TEEC validation
POST	`/scan`	Secret detection
GET	`/health`	Health check
GET	`/ready`	Readiness probe
GET	`/modules`	Active module status

Any language can call POST /evaluate and get a governance Decision back:

curl -X POST http://localhost:8080/evaluate \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello", "tool": "web_search", "agent_id": "bot-1"}'

{
  "correlation_id": "req-abc-123",
  "decision": {
    "action": "ALLOW",
    "reason_codes": ["POLICY_COMPLIANT"],
    "risk_score": 0,
    "mode": "ENFORCE"
  }
}

Policy Library

We shipped a Policy Library with 18 copy-paste governance policies, 4 compliance packs (OWASP ASI, HIPAA, SOC 2, EU AI Act), and 5 use case starters (customer support, code assistant, RAG, healthcare, financial advisor).

Pick a template. Tweak thresholds. Deploy.

Three-Mode Rollout

Governance adoption doesn't have to be all-or-nothing:

REPORT_ONLY — Log everything, enforce nothing. See what would happen.
MONITOR — Evaluate fully, but override all decisions to ALLOW. Log what would have been blocked.
ENFORCE — Full enforcement. The decision is final.

Start with REPORT_ONLY in production. Graduate to MONITOR. Switch to ENFORCE when you trust the policy.

Numbers

1,657 tests passing
32 reason codes across 8 categories
18 event types across 8 modules
12 decision actions with severity-based merge
7 LLM providers (95%+ market coverage)
< 15ms p99 evaluation latency (4 modules, parallel)
100% backward compatible with v1.1.x

Getting Started

# TypeScript
npm install tealtiger

# Python
pip install tealtiger

# Docker (language-agnostic)
docker pull tealtigeradmin/tealtiger-typescript:1.2-governance

import { TealEngineV12, TealSecrets, TealRegistry, PolicyMode } from 'tealtiger';

const engine = new TealEngineV12({
  policy: {
    secrets: { enabled: true },
    registry: { models: ['gpt-4o'], tools: ['web_search'] }
  },
  modules: [new TealSecrets(), new TealRegistry()],
  mode: PolicyMode.ENFORCE
});

const decision = await engine.evaluateV12(
  { content: 'Process this request', model: 'gpt-4o', tool: 'web_search' },
  { correlation_id: 'req-001', agent_id: 'support-bot' }
);

DEV Community