Policy Evaluation Logic - TealTiger Docs

TealTiger uses a deterministic evaluation pipeline. Same input + same policy = same decision, every time. There is no LLM in the governance path — no probabilistic scoring, no prompt-dependent behavior. This makes every governance decision auditable, reproducible, and testable. This page is the definitive reference for how TealEngine v1.2 evaluates a request from the moment it arrives to the final Decision object returned to your application.

This documents the v1.2 evaluation pipeline (TealEngineV12). The v1.1 TealEngine uses a simpler sequential pipeline. See the migration guide for differences.

Evaluation Flowchart

The following diagram shows the complete decision path for every request that enters TealEngine v1.2:

TealTiger Policy Evaluation Logic Flowchart — shows the full decision pipeline from request arrival through mode check, module resolution, parallel dispatch, failure handling, result merge, mode override, TEEC validation, and final decision

Each diamond is a branching decision. Each rounded rectangle is a processing step. Red paths lead to DENY outcomes. Green paths lead to ALLOW outcomes. The teal path is the normal evaluation flow.

Step-by-Step Evaluation

Step 1: Request Arrives

Every evaluation starts with a request object and a ModuleContext. The request contains the data being governed (model, messages, tool calls, etc.). The context carries metadata that ties the evaluation to your system.

const decision = await engine.evaluateV12(
  { model: 'gpt-4o', messages: [{ role: 'user', content: '...' }] },
  { correlation_id: 'req-001', agent_id: 'support-bot', tenant_id: 'acme' }
);

The correlation_id is required — it ties the entire evaluation chain together across your system. The engine uses it in the final Decision, in audit logs, and in TEEC evidence envelopes. If you’re using OpenTelemetry, this maps to your trace ID.

Step 2: Check Policy Mode

The first thing the engine checks is the policy mode. TealTiger supports three modes that control how strictly the pipeline enforces decisions:

Mode	Behavior
`ENFORCE`	Full evaluation. The merged action is returned as-is. Default.
`MONITOR`	Full evaluation, but the final action is overridden to `ALLOW`. Violations are logged with reason codes.
`REPORT_ONLY`	No evaluation. Returns `ALLOW` immediately. Logs the request for audit purposes only.

If the mode is REPORT_ONLY, the engine skips the entire evaluation pipeline, logs the request, and returns ALLOW immediately. This is useful for onboarding — deploy TealTiger in production without affecting any traffic, and review what would have been evaluated.

const engine = new TealEngineV12({
  policy: myPolicy,
  mode: PolicyMode.REPORT_ONLY, // Skip evaluation, log only
  modules: [new TealSecrets(), new TealRegistry()]
});

const decision = await engine.evaluateV12(request, { correlation_id: 'req-001' });
// decision.action === 'ALLOW' (always, in REPORT_ONLY mode)

Start with REPORT_ONLY in production, then graduate to MONITOR, then ENFORCE. This is the same phased rollout pattern used by AWS IAM’s permission boundaries and Google Cloud’s Organization Policy dry-run mode.

Step 3: Resolve Required Modules

The engine inspects the policy object for top-level keys that match registered module names. Only modules referenced by the policy are activated — if your policy doesn’t include a secrets key, TealSecrets is never initialized or invoked.

const policy = {
  secrets: { enabled: true, patterns: ['aws', 'github'] },  // → TealSecrets
  memory: { default_scope: 'session' },                      // → TealMemory
  registry: { allowlist: ['gpt-4o', 'claude-3.5-sonnet'] }   // → TealRegistry
};
// Engine resolves: ['tealsecrets', 'tealmemory', 'tealregistry']

If a policy references a module that isn’t registered, the engine throws TealConfigError immediately — fail-fast, no silent skips:

try {
  await engine.evaluateV12(request, { correlation_id: 'req-001' });
} catch (err) {
  if (err instanceof TealConfigError) {
    console.error(err.code);    // 'MODULE_NOT_REGISTERED'
    console.error(err.details); // { config_key: 'secrets', module: 'tealsecrets' }
  }
}

This is a configuration error, not a runtime governance decision. It means your deployment is misconfigured. The engine throws rather than silently skipping the module — silent skips would create a false sense of security.

Step 4: Lazy Initialization

Modules are initialized on first use, not at engine construction. When a module is needed for the first time, the engine calls init() with the module’s policy config. Once initialized, a module stays initialized for the engine’s lifetime.

First request with secrets policy:
  → TealSecrets.init({ enabled: true, patterns: ['aws'] })
  → Module marked as initialized

Second request:
  → TealSecrets already initialized, skip init()

This means the first evaluation that activates a new module may be slightly slower due to initialization overhead. Subsequent evaluations reuse the initialized module.

Step 5: Parallel Dispatch

All resolved modules are dispatched simultaneously using Promise.allSettled (TypeScript) or asyncio.gather (Python). This is the key architectural difference from v1.1, which ran modules sequentially.

                    ┌─────────────┐
                    │   Request    │
                    └──────┬──────┘
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        TealSecrets   TealRegistry  TealMemory
              ▼            ▼            ▼
              └────────────┼────────────┘
                    ┌──────┴──────┐
                    │    Merge    │
                    └─────────────┘

Each module receives the same request, ModuleContext, and full policy. Modules are independent — they don’t see each other’s results.

// Internally, the engine does:
const settled = await Promise.allSettled(
  requiredModules.map(name => {
    const mod = moduleRegistry.get(name);
    return mod.evaluate(request, ctx, policy);
  })
);

Promise.allSettled (not Promise.all) is used deliberately. If one module throws, the others still complete. The engine handles failures in the next step rather than aborting the entire evaluation.

Why parallel? In v1.1, if you had 4 modules each taking 50ms, total latency was 200ms. In v1.2, total latency is ~50ms (the slowest module). For latency-sensitive applications (chat, code completion), this matters.

Step 6: Failure Handling

After all modules settle, the engine separates successful results from failures. What happens next depends on the failurePolicy configuration: FAIL_CLOSED (default): If any module threw an error, the entire evaluation returns DENY with reason "Module(s) failed". Failed module names appear in metadata.modules_failed.

// If TealSecrets throws an internal error:
const decision = await engine.evaluateV12(request, { correlation_id: 'req-001' });
// decision.action === 'DENY'
// decision.reason === 'Module(s) failed: tealsecrets. Fail-closed default applied.'
// decision.metadata.failed_modules === [{ name: 'tealsecrets', error: '...' }]

FAIL_OPEN: The failed module is ignored, and evaluation continues with successful modules only.

const engine = new TealEngineV12({
  policy: myPolicy,
  modules: [new TealSecrets(), new TealMemory()],
  failurePolicy: { default: 'FAIL_OPEN' }
});
// If TealSecrets throws but TealMemory succeeds:
// → Engine continues with TealMemory's result only

FAIL_OPEN should only be used in development or MONITOR mode environments. In production with ENFORCE mode, always use FAIL_CLOSED. A module that can’t evaluate is a module that can’t protect you.

Step 7: Result Merge — “Most Restrictive Wins”

All successful module results are merged using action severity ranking. The action with the highest severity becomes the final action. All reason codes from all modules are combined (union). All findings (e.g., SecretFinding) are combined.

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`

Merge Example

Three modules evaluate the same request:

Module	Action	Severity	Reason Codes
TealSecrets	`REDACT`	70	`SECRET_DETECTED`
TealRegistry	`ALLOW`	0	`POLICY_COMPLIANT`
TealMemory	`ALLOW_WRITE`	0	`POLICY_COMPLIANT`

Merged result:

Action: REDACT (severity 70 — highest)
Reason codes: ['SECRET_DETECTED', 'POLICY_COMPLIANT'] (union from all modules)
Event type: from the winning module (secret.detection)

When two modules return actions with the same severity (e.g., DENY and DENY_WRITE), the engine uses the action from the module that appears first in the evaluation order. Both modules’ reason codes are still combined.

Step 8: Mode Override

After merging, the engine checks the mode one more time:

MONITOR: The merged action is logged but overridden to ALLOW. The original action is preserved in metadata for analysis.
ENFORCE: The merged action is the final action — no override.

const engine = new TealEngineV12({
  policy: myPolicy,
  mode: PolicyMode.MONITOR,
  modules: [new TealSecrets()]
});

const decision = await engine.evaluateV12(request, { correlation_id: 'req-001' });
// decision.action === 'ALLOW'  (overridden)
// decision.reason_codes === ['SECRET_DETECTED']  (preserved)

MONITOR mode is your shadow-testing tool. Deploy it for a week, review the decisions in your audit log, then flip to ENFORCE when you’re confident in the policy.

Step 9: TEEC Validation

The final Decision is validated against the TEEC registry (Typed Evidence & Evidence Contracts). This checks:

Are all reason_codes registered TEEC reason codes?
Is the event_type a valid TEEC event type?
Is the action a registered TEEC decision action?

Validation is non-blocking — invalid fields produce warnings in metadata.teec_warnings. The decision is returned regardless of validation result.

const decision = await engine.evaluateV12(request, { correlation_id: 'req-001' });

if (decision.metadata.teec_warnings) {
  console.warn('TEEC validation warnings:', decision.metadata.teec_warnings);
  // [{ field: 'reason_codes', value: 'CUSTOM_CODE', valid: false,
  //    message: 'Reason code not found in TEEC registry' }]
}

TEEC validation is intentionally non-blocking so that custom modules with custom reason codes don’t break the evaluation pipeline. The warnings give you visibility without disrupting governance.

Step 10: Return Decision

The complete Decision object is returned with all fields populated:

interface Decision {
  action: DecisionAction;           // The final governance action
  reason_codes: ReasonCode[];       // All reason codes from all modules
  risk_score: number;               // 0–100, derived from action severity
  mode: PolicyMode;                 // ENFORCE | MONITOR | REPORT_ONLY
  policy_id: string;                // Policy identifier
  policy_version: string;           // Policy version (e.g., "1.2.0")
  component_versions: {             // SDK and engine versions
    sdk: string;
    engine: string;
  };
  correlation_id: string;           // Request correlation ID
  reason: string;                   // Human-readable explanation
  event_type: string;               // TEEC event type
  teec_version: string;             // TEEC registry version
  timestamp: number;                // Unix ms
  module: string;                   // Originating module
  metadata: Record<string, unknown>; // Extra data
  findings?: SecretFinding[];       // Secret findings (if TealSecrets active)
}

The metadata object includes:

evaluation_time_ms — How long the evaluation took
modules_evaluated — Which modules ran successfully
modules_failed — Which modules failed (if any)
teec_warnings — TEEC validation warnings (if any)

Key Principles

Principle 1: Explicit Deny Overrides Everything

Like AWS IAM, a DENY from any module overrides ALLOW from all others. There is no way to “un-deny” a request. This is a security-first design choice — you can’t accidentally allow something that any governance dimension flags.

TealSecrets: DENY (severity 100)
TealRegistry: ALLOW (severity 0)
TealMemory: ALLOW_WRITE (severity 0)
─────────────────────────────────
Final: DENY (most restrictive wins)

Principle 2: No LLM in the Governance Path

The evaluation pipeline is pure deterministic logic. No model inference, no probabilistic decisions. Pattern matching, severity ranking, and boolean logic — that’s it. This is what makes TealTiger’s decisions reconstructable and auditable.

Principle 3: Fail-Closed by Default

If the governance system itself fails (a module throws an exception), the default is to deny. This prevents a broken guardrail from becoming an open door. You can override this with FAIL_OPEN, but it’s not recommended for production.

Principle 4: Evidence by Default

Every evaluation produces a structured evidence envelope (TEEC). You don’t opt into evidence — you opt out of it. Every Decision includes correlation IDs, timestamps, reason codes, component versions, and module metadata.

Examples

Example 1: Simple ALLOW

A request passes all governance modules. No violations detected. Policy:

{
  "secrets": { "enabled": true },
  "registry": { "allowlist": ["gpt-4o"] }
}

Request:

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "What is the weather today?" }]
}

What each module returns:

Module	Action	Reason Codes
TealSecrets	`ALLOW`	`POLICY_COMPLIANT`
TealRegistry	`ALLOW`	`POLICY_COMPLIANT`

Merge result: ALLOW (both severity 0) Final Decision:

{
  action: 'ALLOW',
  reason_codes: ['POLICY_COMPLIANT'],
  risk_score: 0,
  reason: 'Request allowed — all governance checks passed',
  metadata: {
    evaluation_time_ms: 12,
    modules_evaluated: ['tealsecrets', 'tealregistry'],
    modules_failed: []
  }
}

Example 2: Single Module DENY

TealSecrets detects an AWS access key in the message content. TealRegistry allows the model. Policy:

{
  "secrets": { "enabled": true, "patterns": ["aws"] },
  "registry": { "allowlist": ["gpt-4o"] }
}

Request:

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": "Deploy with key AKIAIOSFODNN7EXAMPLE and secret wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }]
}

What each module returns:

Module	Action	Severity	Reason Codes
TealSecrets	`DENY`	100	`SECRET_DETECTED`, `CREDENTIAL_LEAKAGE`
TealRegistry	`ALLOW`	0	`POLICY_COMPLIANT`

Merge result: DENY (severity 100 overrides severity 0) Final Decision:

{
  action: 'DENY',
  reason_codes: ['SECRET_DETECTED', 'CREDENTIAL_LEAKAGE', 'POLICY_COMPLIANT'],
  risk_score: 100,
  reason: 'Governance action: DENY. Reason codes: SECRET_DETECTED, CREDENTIAL_LEAKAGE, POLICY_COMPLIANT',
  findings: [
    { type: 'aws_access_key', confidence: 0.95, severity: 'critical', fingerprint: 'sha256:...' },
    { type: 'aws_secret_key', confidence: 0.92, severity: 'critical', fingerprint: 'sha256:...' }
  ],
  metadata: {
    evaluation_time_ms: 18,
    modules_evaluated: ['tealsecrets', 'tealregistry'],
    modules_failed: []
  }
}

Example 3: REQUIRE_APPROVAL

A cost governance module detects that the request’s estimated cost exceeds a threshold. Policy:

{
  "secrets": { "enabled": true },
  "registry": { "allowlist": ["gpt-4o"], "cost_threshold": 5.00 }
}

Request:

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "Analyze this 200-page document..." }],
  "estimated_cost_usd": 8.50
}

What each module returns:

Module	Action	Severity	Reason Codes
TealSecrets	`ALLOW`	0	`POLICY_COMPLIANT`
TealRegistry	`REQUIRE_APPROVAL`	80	`COST_VELOCITY_ANOMALY`

Merge result: REQUIRE_APPROVAL (severity 80 > severity 0) Final Decision:

{
  action: 'REQUIRE_APPROVAL',
  reason_codes: ['POLICY_COMPLIANT', 'COST_VELOCITY_ANOMALY'],
  risk_score: 80,
  reason: 'Governance action: REQUIRE_APPROVAL. Reason codes: POLICY_COMPLIANT, COST_VELOCITY_ANOMALY',
  metadata: {
    evaluation_time_ms: 15,
    modules_evaluated: ['tealsecrets', 'tealregistry'],
    modules_failed: []
  }
}

Example 4: MONITOR Mode

The same secret-detection DENY from Example 2, but the engine is in MONITOR mode. The action is overridden to ALLOW, but the violation is fully logged. Policy:

{
  "secrets": { "enabled": true }
}

Engine configuration:

const engine = new TealEngineV12({
  policy: { secrets: { enabled: true } },
  mode: PolicyMode.MONITOR,  // Shadow testing
  modules: [new TealSecrets()]
});

Request:

{
  "model": "gpt-4o",
  "messages": [{
    "role": "user",
    "content": "Use key AKIAIOSFODNN7EXAMPLE to access S3"
  }]
}

What TealSecrets returns:

Module	Action	Severity	Reason Codes
TealSecrets	`DENY`	100	`SECRET_DETECTED`

Merge result: DENY (severity 100) Mode override: MONITOR → override to ALLOW Final Decision:

{
  action: 'ALLOW',           // Overridden by MONITOR mode
  mode: 'MONITOR',
  reason_codes: ['SECRET_DETECTED'],  // Violation preserved
  risk_score: 0,
  reason: 'Request allowed — all governance checks passed',
  metadata: {
    evaluation_time_ms: 14,
    modules_evaluated: ['tealsecrets'],
    modules_failed: [],
    // The audit log captures what would have happened in ENFORCE mode
  }
}

Use MONITOR mode to build a baseline of what TealTiger would block before enabling enforcement. Review the audit log for false positives and tune your policy accordingly.

Example 5: Module Failure (Fail-Closed)

A module throws an unexpected error during evaluation. With the default FAIL_CLOSED policy, the engine returns DENY. Policy:

{
  "secrets": { "enabled": true },
  "registry": { "allowlist": ["gpt-4o"] }
}

Engine configuration:

const engine = new TealEngineV12({
  policy: { secrets: { enabled: true }, registry: { allowlist: ['gpt-4o'] } },
  mode: PolicyMode.ENFORCE,
  modules: [new TealSecrets(), new TealRegistry()],
  failurePolicy: { default: 'FAIL_CLOSED' }  // This is the default
});

Request:

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "Hello" }]
}

What happens: TealSecrets throws an internal error (e.g., pattern file corrupted). TealRegistry returns ALLOW.

Module	Result	Reason Codes
TealSecrets	ERROR (threw exception)	—
TealRegistry	`ALLOW`	`POLICY_COMPLIANT`

Failure policy: FAIL_CLOSED → entire evaluation returns DENY Final Decision:

{
  action: 'DENY',
  reason_codes: ['POLICY_VIOLATION'],
  risk_score: 100,
  reason: 'Module(s) failed: tealsecrets. Fail-closed default applied.',
  metadata: {
    evaluation_time_ms: 5,
    modules_evaluated: [],
    modules_failed: [{ name: 'tealsecrets', error: 'Pattern file corrupted' }]
  }
}

Fail-closed means “when in doubt, deny.” This is the same principle behind AWS IAM’s implicit deny — if the system can’t determine whether to allow, it denies.

Comparison with AWS IAM

TealTiger’s policy evaluation shares several design principles with AWS IAM, adapted for AI agent governance:

Aspect	AWS IAM	TealTiger
Evaluation model	Sequential (deny overrides allow)	Parallel (most restrictive wins)
Decision types	Allow / Deny	12 actions (Allow, Deny, Redact, Degrade, etc.)
Policy language	JSON policy documents	JSON policy objects with module keys
Modes	N/A	`ENFORCE`, `MONITOR`, `REPORT_ONLY`
Evidence	CloudTrail logs	TEEC evidence envelopes (SARIF, JUnit, JSON)
Failure behavior	Implicit deny	Configurable (`FAIL_CLOSED` / `FAIL_OPEN`)
Deterministic	Yes — same policy + same request = same result	Yes — no LLM in the governance path
Explicit deny wins	Yes — explicit deny overrides any allow	Yes — `DENY` (severity 100) overrides all
Merge strategy	Explicit deny > explicit allow > implicit deny	Most restrictive action wins (severity ranking)
Typed evidence	CloudTrail event schema	TEEC (Typed Evidence & Evidence Contract)

The key difference: TealTiger evaluates modules in parallel, while AWS IAM evaluates policy types sequentially. This is possible because TealTiger modules are independent — they don’t depend on each other’s results. The merge step handles conflicts after all modules complete.

Module System — How modules are registered, initialized, and dispatched
TEEC — Typed Evidence & Evidence Contracts — The evidence schema behind every decision
Decision Lifecycle — From request to audit log
Decision Model — The Decision object in detail
Policy Modes — ENFORCE, MONITOR, REPORT_ONLY deep dive
TealEngineV12 API Reference — Full API documentation

​Evaluation Flowchart

​Step-by-Step Evaluation

​Step 1: Request Arrives

​Step 2: Check Policy Mode

​Step 3: Resolve Required Modules

​Step 4: Lazy Initialization

​Step 5: Parallel Dispatch

​Step 6: Failure Handling

​Step 7: Result Merge — “Most Restrictive Wins”

​Merge Example

​Step 8: Mode Override

​Step 9: TEEC Validation

​Step 10: Return Decision

​Key Principles

​Principle 1: Explicit Deny Overrides Everything

​Principle 2: No LLM in the Governance Path

​Principle 3: Fail-Closed by Default

​Principle 4: Evidence by Default

​Examples

​Example 1: Simple ALLOW

​Example 2: Single Module DENY

​Example 3: REQUIRE_APPROVAL

​Example 4: MONITOR Mode

​Example 5: Module Failure (Fail-Closed)

​Comparison with AWS IAM

​Related Documentation

Evaluation Flowchart

Step-by-Step Evaluation

Step 1: Request Arrives

Step 2: Check Policy Mode

Step 3: Resolve Required Modules

Step 4: Lazy Initialization

Step 5: Parallel Dispatch

Step 6: Failure Handling

Step 7: Result Merge — “Most Restrictive Wins”

Merge Example

Step 8: Mode Override

Step 9: TEEC Validation

Step 10: Return Decision

Key Principles

Principle 1: Explicit Deny Overrides Everything

Principle 2: No LLM in the Governance Path

Principle 3: Fail-Closed by Default

Principle 4: Evidence by Default

Examples

Example 1: Simple ALLOW

Example 2: Single Module DENY

Example 3: REQUIRE_APPROVAL

Example 4: MONITOR Mode

Example 5: Module Failure (Fail-Closed)

Comparison with AWS IAM

Related Documentation