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

codes, and component_versions` directly into every decision envelope.

• 12-Graduated Action Scale provides fine-grained control (from DENY to ALLOW) without binary policy conflicts.

Core Solution

TealTiger v1.2 is a deterministic governance engine that evaluates every agent action against policy at runtime. The architecture decomposes governance into independent, parallel-running modules, each owning a single security dimension.

Parallel Module Evaluation

Instead of a monolithic evaluator, v1.2 routes requests through independent modules that execute concurrently:

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

Enter fullscreen mode Exit fullscreen mode

The merge strategy follows a strict hierarchy: most restrictive action wins. If TealSecrets returns DENY and TealRegistry returns ALLOW, the final decision is DENY. There is no mechanism to "un-deny" a request, mirroring AWS IAM's explicit deny principle but extended across 12 graduated actions.

Action Severity Scale

Actions are ranked by severity to enable deterministic merging:

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

Module exceptions never degrade security posture. Any evaluation failure triggers an immediate DENY:

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

Enter fullscreen mode Exit fullscreen mode

The 7 Governance Modules

1. 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). Returns confidence scores and content fingerprints without exposing raw secrets.

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

Enter fullscreen mode Exit fullscreen mode

2. TealRegistry — Model & Tool Allowlisting: Enforces strict model/tool invocation boundaries. 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()]
});

Enter fullscreen mode Exit fullscreen mode

3. TealReliability — Circuit Breakers & Fallbacks: Implements retry budgets, 3-state circuit breakers (closed/open/half-open), fallback chains, and degradation policies to prevent cascading failures and cost overruns.
4. TealMemory — Memory Governance: Controls read/write access across 5 scopes (session, agent, user, shared, global) and 4 classification levels (public, internal, confidential, restricted). Introduces 5 memory-specific decision actions.
5. BundleExporter — Evidence Export: Structures every decision into exportable envelopes (SARIF v2.1.0, JUnit XML, JSON) for security tooling and CI/CD pipelines.
6. GovernanceDashboard & TEECValidationRunner: Visualizes policy impact and validates evidence contracts against the TEEC registry.

TEEC — Typed Evidence & Evidence Contracts

Every decision is validated against an explicit contract:

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

TEEC embeds correlation_id, timestamp, reason_codes, event_type, teec_version, and component_versions into every response, guaranteeing post-incident reconstructability.

Docker Governance Sidecar

Polyglot environments are supported via a language-agnostic HTTP API:

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

Enter fullscreen mode Exit fullscreen mode

Available 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 invoke evaluation:

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

Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode

Three-Mode Rollout

Governance adoption follows a graduated enforcement model:

1. REPORT_ONLY — Log all evaluations, enforce nothing. Baseline policy impact.
2. MONITOR — Evaluate fully, override decisions to ALLOW, log blocked actions.
3. ENFORCE — Full enforcement. Decisions are final.

Start with REPORT_ONLY in production, graduate to MONITOR, and switch to ENFORCE only after policy validation.

Pitfall Guide

1. Bypassing Determinism with LLM-based Scoring: Introducing probabilistic models into the decision path destroys auditability and increases latency. Keep the governance path strictly pattern-matching and boolean-logic-driven.
2. Ignoring the "Most Restrictive Wins" Merge Strategy: Assuming ALLOW can override DENY creates policy conflicts. Design policies knowing that explicit denies are irreversible and will always win the merge.
3. Skipping the REPORT_ONLY → MONITOR → ENFORCE Rollout: Deploying directly to ENFORCE mode without telemetry causes production outages and agent deadlocks. Always validate policy impact in logging-only mode first.
4. Neglecting TEEC Evidence Contracts: Failing to enforce structured reason codes and correlation IDs makes compliance audits impossible. Every decision must carry a complete TEEC envelope for legal and security traceability.
5. Assuming Fail-Closed Means Zero False Positives: Fail-closed defaults prioritize security over availability. Tune TealReliability circuit breakers and fallback chains to handle legitimate traffic spikes without triggering blanket denies.
6. Hardcoding Tool/Model Allowlists Without Provenance Verification: Static allowlists become stale and vulnerable to supply-chain attacks. Always enable version pinning and provenance verification in TealRegistry to prevent unauthorized model/tool swaps.

Deliverables

• 📘 TealTiger v1.2 Architecture & Deployment Blueprint: Complete reference architecture detailing parallel module routing, TEEC contract validation, Docker sidecar integration, and fail-closed error handling patterns.
• ✅ Governance Rollout & Compliance Checklist: Step-by-step verification guide covering policy library selection, three-mode rollout phases, TEEC evidence validation, secret scanning coverage, and audit trail configuration for SOC 2 / HIPAA / EU AI Act compliance.
• ⚙️ Policy Library & Configuration Templates: 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) with pre-tuned thresholds and TEEC-mapped reason codes.