TealEngineV12

TealEngineV12 is the v1.2 governance orchestration engine. It dispatches to all active modules in parallel, merges results using “most restrictive action wins”, and validates every decision against the TEEC registry.

TealEngineV12 is a new class — it does not replace or extend the v1.1 TealEngine. Both can coexist in the same application.

Class

class TealEngineV12 {
  constructor(options: TealEngineV12Options);

  evaluateV12(
    request: Record<string, unknown>,
    ctx: Partial<ModuleContext> & { correlation_id: string }
  ): Promise<Decision>;

  getModuleStatus(): ModuleStatusMap;
  getTEECRegistry(): TEECRegistry;
  getTEECValidator(): TEECValidator;
}

TealEngineV12Options

interface TealEngineV12Options {
  /** Governance modules to register */
  modules?: TealModule[];

  /** Policy configuration — keys map to module dimensions */
  policy: Record<string, unknown>;

  /** Policy mode (default: ENFORCE) */
  mode?: PolicyMode;

  /** Failure handling strategy (default: FAIL_CLOSED) */
  failurePolicy?: FailurePolicyConfig;
}

FailurePolicyConfig

interface FailurePolicyConfig {
  /** Global default: 'FAIL_CLOSED' or 'FAIL_OPEN' */
  default: 'FAIL_CLOSED' | 'FAIL_OPEN';

  /** Override for memory adapter failures */
  memory_adapter_unavailable?: { action: string };

  /** Override for evidence sink failures */
  evidence_sink_unavailable?: { action: string };

  /** Override for bundle fetch failures */
  bundle_fetch_failed?: { action: string; allow_cached_bundle?: boolean };

  /** Override for SARIF export failures */
  sarif_export_failed?: { action: string; emit_evidence?: boolean };
}

Creating an Engine

Basic Setup

import { TealEngineV12, PolicyMode } from 'tealtiger';

const engine = new TealEngineV12({
  policy: {
    tools: { file_delete: { allowed: false } }
  },
  mode: PolicyMode.ENFORCE
});

With Governance Modules

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

const engine = new TealEngineV12({
  policy: {
    secrets: { enabled: true, confidence_threshold: 0.8 },
    registry: {
      models: ['gpt-4', 'gpt-4o', 'claude-3-sonnet'],
      tools: ['web_search', 'file_read']
    },
    reliability: {
      retry_budget: 3,
      circuit_threshold: 5,
      fallback_model: 'gpt-3.5-turbo'
    },
    memory: {
      default_scope: 'session',
      classification: 'internal'
    }
  },
  modules: [
    new TealSecrets(),
    new TealRegistry(),
    new TealReliability(),
    new TealMemory()
  ],
  mode: PolicyMode.ENFORCE,
  failurePolicy: { default: 'FAIL_CLOSED' }
});

evaluateV12()

The primary evaluation method. Dispatches to all active modules in parallel and returns a merged Decision.

Signature

async evaluateV12(
  request: Record<string, unknown>,
  ctx: Partial<ModuleContext> & { correlation_id: string }
): Promise<Decision>

Parameters

Parameter	Type	Required	Description
`request`	`Record<string, unknown>`	Yes	The request to evaluate. Keys depend on which modules are active.
`ctx.correlation_id`	`string`	Yes	Unique request identifier for tracing.
`ctx.tenant_id`	`string`	No	Multi-tenant isolation key.
`ctx.user_id`	`string`	No	End user identifier.
`ctx.session_id`	`string`	No	Session scope identifier.
`ctx.agent_id`	`string`	No	Agent identifier.

Example

import { v4 as uuidv4 } from 'uuid';

const decision = await engine.evaluateV12(
  {
    content: 'Please process this request',
    tool: 'database_query',
    toolParams: { query: 'SELECT * FROM users' },
    model: 'gpt-4'
  },
  {
    correlation_id: uuidv4(),
    agent_id: 'agent-001',
    user_id: 'user-456',
    session_id: 'sess-789'
  }
);

console.log(decision.action);        // 'ALLOW' | 'DENY' | ...
console.log(decision.reason_codes);  // ['POLICY_COMPLIANT']
console.log(decision.risk_score);    // 0-100
console.log(decision.event_type);    // 'policy.evaluation'

ModuleContext

Context passed to every module during evaluation.

interface ModuleContext {
  correlation_id: string;
  tenant_id?: string;
  user_id?: string;
  session_id?: string;
  agent_id?: string;
  policy_version: string;   // "1.2.0"
  teec_version: string;     // "0.1.0"
  timestamp: number;        // Unix ms
}

Decision (v1.2 Extended)

The v1.2 Decision extends the v1.1 type with TEEC evidence fields.

interface Decision {
  // v1.1 fields (preserved)
  action: DecisionAction;
  reason_codes: string[];
  risk_score: number;
  mode: PolicyMode;
  policy_id: string;
  policy_version: string;
  component_versions: ComponentVersions;
  correlation_id: string;
  reason: string;
  metadata: Record<string, unknown>;

  // v1.2 TEEC fields (new)
  event_type?: string;
  teec_version?: string;
  timestamp?: number;
  module?: string;
  registry_refs?: RegistryRef[];
  findings?: SecretFinding[];
}

Decision Metadata (v1.2)

The metadata field includes evaluation telemetry:

{
  evaluation_time_ms: number;      // Total evaluation time
  modules_evaluated: string[];     // Modules that ran successfully
  modules_failed: string[];        // Modules that threw errors
  teec_warnings?: object[];        // TEEC validation warnings
}

DecisionAction (v1.2)

v1.2 adds 5 memory-governance actions to the existing 6:

// v1.1 actions
type DecisionAction =
  | 'ALLOW'
  | 'DENY'
  | 'REDACT'
  | 'DEGRADE'
  | 'REQUIRE_APPROVAL'
  | 'TRANSFORM'
  // v1.2 additions
  | 'ALLOW_WRITE'
  | 'DENY_WRITE'
  | 'REDACT_AND_WRITE'
  | 'STORE_SUMMARY_ONLY'
  | 'DENY_READ';

Helper Methods

getModuleStatus()

Returns the registration and initialization status of all modules.

const status = engine.getModuleStatus();
// {
//   tealsecrets:     { registered: true, initialized: true,  version: '1.2.0' },
//   tealregistry:    { registered: true, initialized: false, version: '1.2.0' },
//   tealreliability: { registered: true, initialized: true,  version: '1.2.0' },
//   tealmemory:      { registered: true, initialized: false, version: '1.2.0' }
// }

getTEECRegistry()

Returns the embedded TEEC registry for inspection.

const registry = engine.getTEECRegistry();
console.log(registry.version);              // "0.1.0"
console.log(registry.reason_codes.size);    // 32
console.log(registry.event_types.size);     // 18
console.log(registry.decision_actions.size); // 12

getTEECValidator()

Returns the TEEC validator for manual decision validation.

const validator = engine.getTEECValidator();
const results = validator.validateDecision(decision);
const isValid = results.every(r => r.valid);

Error Handling

TealConfigError

Thrown when the policy references a module that isn’t registered.

try {
  const decision = await engine.evaluateV12(request, ctx);
} catch (error) {
  if (error instanceof TealConfigError) {
    console.error(`Config error: ${error.message}`);
    console.error(`Code: ${error.code}`);     // 'MODULE_NOT_REGISTERED'
    console.error(`Details:`, error.details);  // { module: 'tealsecrets' }
  }
}

Fail-Closed Decisions

When a module throws during evaluation and failurePolicy.default is 'FAIL_CLOSED', the engine returns a DENY decision instead of throwing:

const decision = await engine.evaluateV12(request, ctx);

if (decision.metadata.modules_failed?.length > 0) {
  console.warn('Some modules failed:', decision.metadata.modules_failed);
  // decision.action will be 'DENY'
  // decision.reason will explain which modules failed
}

Performance

TealEngineV12 targets:

Parallel dispatch — All modules run simultaneously via Promise.allSettled
Lazy initialization — Modules init only on first use
< 15ms per evaluation (p99, 4 modules, without external calls)
Deterministic results — Same inputs + same policy → same outputs

Python Equivalent

from tealtiger import TealEngineV12, PolicyMode

engine = TealEngineV12(
    policy={
        "secrets": {"enabled": True},
        "memory": {"default_scope": "session"}
    },
    modules=[TealSecrets(), TealMemory()],
    mode=PolicyMode.ENFORCE,
    failure_policy={"default": "FAIL_CLOSED"}
)

decision = await engine.evaluate_v12(
    request={"content": "Hello world", "tool": "web_search"},
    ctx={"correlation_id": "req-abc-123", "agent_id": "agent-001"}
)

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Class

TealEngineV12Options

FailurePolicyConfig

Creating an Engine

Basic Setup

With Governance Modules

evaluateV12()

Signature

Parameters

Example

ModuleContext

Decision (v1.2 Extended)

Decision Metadata (v1.2)

DecisionAction (v1.2)

Helper Methods

getModuleStatus()

getTEECRegistry()

getTEECValidator()

Error Handling

TealConfigError

Fail-Closed Decisions

Performance

Python Equivalent

​Class

​TealEngineV12Options

​FailurePolicyConfig

​Creating an Engine

​Basic Setup

​With Governance Modules

​evaluateV12()

​Signature

​Parameters

​Example

​ModuleContext

​Decision (v1.2 Extended)

​Decision Metadata (v1.2)

​DecisionAction (v1.2)

​Helper Methods

​getModuleStatus()

​getTEECRegistry()

​getTEECValidator()

​Error Handling

​TealConfigError

​Fail-Closed Decisions

​Performance

​Python Equivalent

​Related Documentation

Class

TealEngineV12Options

FailurePolicyConfig

Creating an Engine

Basic Setup

With Governance Modules

evaluateV12()

Signature

Parameters

Example

ModuleContext

Decision (v1.2 Extended)

Decision Metadata (v1.2)

DecisionAction (v1.2)

Helper Methods

getModuleStatus()

getTEECRegistry()

getTEECValidator()

Error Handling

TealConfigError

Fail-Closed Decisions

Performance

Python Equivalent

Related Documentation