TealEngineV13

TealEngine v1.3 extends the parallel evaluation pipeline with pre-evaluation stages (FREEZE rules, NHI verification), post-evaluation hooks (evidence emission, response transformation), automation levels, and PLAN_ONLY mode.

TealEngine v1.3 is backward-compatible with v1.2 policies. Existing evaluateV12() calls continue to work. The new evaluate() method adds pre/post stages and automation level support.

Class

class TealEngine {
  constructor(options: TealEngineOptions);

  /** Full v1.3 evaluation with pre/post stages */
  evaluate(
    request: EvaluationRequest,
    ctx: EvaluationContext
  ): Promise<Decision>;

  /** Approve a PENDING decision */
  approveDecision(
    token: string,
    approval: ApprovalInput
  ): Promise<Decision>;

  /** Reject a PENDING decision */
  rejectDecision(
    token: string,
    rejection: RejectionInput
  ): Promise<Decision>;

  /** Load or hot-swap policy bundle */
  loadPolicy(bundle: PolicyBundle): Promise<void>;

  /** Get engine status */
  getStatus(): EngineStatus;

  /** Legacy v1.2 evaluation (preserved for backward compatibility) */
  evaluateV12(
    request: Record<string, unknown>,
    ctx: Partial<ModuleContext> & { correlation_id: string }
  ): Promise<Decision>;
}

TealEngineOptions

interface TealEngineOptions {
  /** Policy configuration */
  policy: PolicyConfig;

  /** FREEZE rules — immutable safety controls */
  freeze?: FreezeRule[];

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

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

  /** Failure handling strategy */
  failurePolicy?: FailurePolicyConfig;

  /** NHI governance configuration */
  nhi?: NHIConfig;

  /** Post-evaluation hooks */
  postHooks?: PostEvaluationHook[];

  /** Approval configuration */
  approval?: ApprovalConfig;
}

evaluate()

The primary v1.3 evaluation method. Executes the full pipeline:

FREEZE Check → NHI Verification → Pre-Evaluation → Module Dispatch → Merge → Automation → Post-Hooks → Decision

Signature

async evaluate(
  request: EvaluationRequest,
  ctx: EvaluationContext
): Promise<Decision>

EvaluationRequest

interface EvaluationRequest {
  /** Action being performed */
  action: string;

  /** Content being governed (messages, prompts, etc.) */
  content?: string | Message[];

  /** Tool being invoked */
  tool?: string;

  /** Tool parameters */
  toolParams?: Record<string, unknown>;

  /** Model being used */
  model?: string;

  /** Target environment */
  environment?: string;

  /** Additional request metadata */
  metadata?: Record<string, unknown>;
}

EvaluationContext

interface EvaluationContext {
  /** Required: correlation ID for tracing */
  correlation_id: string;

  /** Agent identity */
  agentId?: string;

  /** Agent attestation token */
  attestation?: AttestationToken;

  /** Tenant isolation */
  tenant_id?: string;

  /** End user */
  user_id?: string;

  /** Session */
  session_id?: string;

  /** Evaluation mode override */
  mode?: 'ENFORCE' | 'MONITOR' | 'REPORT_ONLY' | 'PLAN_ONLY';
}

Example

import { TealEngine } from 'tealtiger';
import { v4 as uuidv4 } from 'uuid';

const engine = new TealEngine({
  policy: {
    rules: [
      {
        condition: { action: 'file.write', path: { pattern: '/etc/**' } },
        automation: 'approval_required',
        approval: { approvers: ['[email protected]'], timeout: '10m' }
      },
      {
        condition: { action: 'file.read' },
        automation: 'auto_allow'
      }
    ]
  },
  freeze: [
    {
      id: 'FREEZE-001',
      condition: { action: 'system.shutdown' },
      reason: 'FREEZE_SYSTEM_SHUTDOWN',
      severity: 'critical'
    }
  ],
  modules: [new TealClassifier(), new TealDrift()],
  mode: 'ENFORCE'
});

const decision = await engine.evaluate(
  {
    action: 'file.write',
    toolParams: { path: '/etc/nginx/nginx.conf', content: '...' },
    environment: 'production'
  },
  {
    correlation_id: uuidv4(),
    agentId: 'deploy-agent-001',
    attestation: { token: 'eyJ...', method: 'signed-jwt' }
  }
);

if (decision.pending) {
  console.log('Awaiting approval:', decision.approval.token);
} else {
  console.log('Decision:', decision.action);
}

PLAN_ONLY Mode

Returns what the governance decision would be without executing enforcement or emitting evidence. Useful for agent planning loops and UI previews.

const plan = await engine.evaluate(
  { action: 'database.migrate', environment: 'production' },
  { correlation_id: uuidv4(), mode: 'PLAN_ONLY' }
);

// plan.action === 'PENDING' (what would happen)
// plan.automation_level === 'approval_required'
// plan.executed === false
// plan.plan === true
// No evidence emitted, no approval token created

approveDecision()

Resolves a PENDING decision by providing human approval.

async approveDecision(
  token: string,
  approval: ApprovalInput
): Promise<Decision>

interface ApprovalInput {
  /** Who approved */
  approvedBy: string;

  /** Why they approved */
  justification: string;

  /** Optional: additional conditions on the approval */
  conditions?: Record<string, unknown>;
}

Example

const finalDecision = await engine.approveDecision(
  'approval-token-xyz789',
  {
    approvedBy: '[email protected]',
    justification: 'Reviewed nginx config change — safe to proceed'
  }
);

// finalDecision.action === 'ALLOW'
// finalDecision.approval.status === 'APPROVED'
// finalDecision.approval.evidence.signature === '...' (non-repudiation)

rejectDecision()

Resolves a PENDING decision by rejecting it.

const rejection = await engine.rejectDecision(
  'approval-token-xyz789',
  {
    rejectedBy: '[email protected]',
    reason: 'Config change not reviewed by security team'
  }
);

// rejection.action === 'DENY'
// rejection.approval.status === 'REJECTED'

loadPolicy()

Hot-swap the policy bundle at runtime. FREEZE rules are preserved across swaps.

async loadPolicy(bundle: PolicyBundle): Promise<void>

interface PolicyBundle {
  /** Policy version identifier */
  version: string;

  /** Policy rules */
  rules: PolicyRule[];

  /** Module-specific configuration */
  modules?: Record<string, unknown>;

  /** Bundle integrity hash */
  integrity?: string;

  /** Bundle signature for verification */
  signature?: string;
}

Example

// Load a new policy bundle (FREEZE rules preserved)
await engine.loadPolicy({
  version: '2.1.0',
  rules: updatedRules,
  modules: { classifier: { mode: 'ensemble_union' } },
  integrity: 'sha256:abc123...',
  signature: 'sig:...'
});

If the bundle includes an integrity hash, TealEngine validates it before applying. A mismatched hash triggers BUNDLE_INTEGRITY_VIOLATION and the swap is rejected. See Anti-Tamper Controls.

Pre-Evaluation Pipeline

The v1.3 pre-evaluation pipeline runs before module dispatch:

// Pre-evaluation stages (in order):
// 1. FREEZE rule check — immutable safety gate
// 2. NHI verification — identity attestation
// 3. NHI scope check — permission verification
// 4. JIT grant check — temporal access validation
// 5. Temporal constraints — time-of-day, cooldown, TTL

If any pre-evaluation stage fails, the pipeline short-circuits with DENY. No modules are invoked.

Post-Evaluation Hooks

Post-evaluation hooks run after the decision is computed but before it’s returned:

interface PostEvaluationHook {
  /** Hook identifier */
  id: string;

  /** When to run this hook */
  trigger: 'always' | 'on_deny' | 'on_allow' | 'on_pending';

  /** Hook handler */
  handler: (decision: Decision, ctx: EvaluationContext) => Promise<void>;
}

const engine = new TealEngine({
  policy: myPolicy,
  postHooks: [
    {
      id: 'siem-export',
      trigger: 'on_deny',
      handler: async (decision, ctx) => {
        await siemClient.emit({
          event: 'governance.deny',
          correlation_id: ctx.correlation_id,
          reason_codes: decision.reason_codes,
          agent_id: ctx.agentId
        });
      }
    },
    {
      id: 'metrics',
      trigger: 'always',
      handler: async (decision) => {
        metrics.increment('governance.evaluations', {
          action: decision.action,
          automation_level: decision.automation_level
        });
      }
    }
  ]
});

Decision (v1.3 Extended)

interface Decision {
  // Core fields
  action: DecisionAction;
  reason_codes: string[];
  risk_score: number;
  mode: PolicyMode;
  correlation_id: string;
  reason: string;
  timestamp: number;

  // v1.3 additions
  automation_level: AutomationLevel;
  pending: boolean;
  plan: boolean;
  executed: boolean;

  // Approval (when pending === true)
  approval?: ApprovalState;

  // Pre-evaluation results
  preEvaluation?: {
    freezeChecked: boolean;
    nhiVerified: boolean;
    scopeChecked: boolean;
    temporalChecked: boolean;
  };

  // Evidence
  metadata: Record<string, unknown>;
  findings?: Finding[];
}

Error Handling

import {
  TealConfigError,
  FreezeViolationError,
  BundleIntegrityError,
  ApprovalExpiredError
} from 'tealtiger';

try {
  const decision = await engine.evaluate(request, ctx);
} catch (error) {
  if (error instanceof FreezeViolationError) {
    // Attempted to modify a FREEZE rule
    console.error(`FREEZE tamper: ${error.ruleId}`);
  } else if (error instanceof BundleIntegrityError) {
    // Policy bundle failed integrity check
    console.error(`Bundle integrity: ${error.expected} !== ${error.actual}`);
  } else if (error instanceof ApprovalExpiredError) {
    // Tried to approve an expired token
    console.error(`Token expired: ${error.token}`);
  }
}

Performance

Metric	Target	Notes
Pre-evaluation (FREEZE + NHI)	< 2ms	In-memory checks, no I/O
Module dispatch (parallel)	< 15ms p99	Same as v1.2
Post-hooks	< 5ms	Async, non-blocking
Total evaluate()	< 25ms p99	End-to-end with 4 modules
PLAN_ONLY mode	< 10ms p99	Skips evidence emission

Migration from v1.2

// v1.2 — still works in v1.3
const decision = await engine.evaluateV12(request, { correlation_id: '...' });

// v1.3 — new evaluate() with full pipeline
const decision = await engine.evaluate(
  { action: 'tool.invoke', tool: 'web_search', content: '...' },
  { correlation_id: '...', agentId: 'agent-001' }
);

The evaluateV12() method is preserved for backward compatibility. It bypasses pre-evaluation stages and automation levels, behaving identically to v1.2.

FREEZE Rules — Immutable safety controls
Automation Levels — The four automation levels
NHI Governance — Identity verification pipeline
TealProof — Cryptographic evidence for decisions
TealFlow — Declarative governance workflows
Migration Guide v1.3 — Upgrade path from v1.2

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Class

TealEngineOptions

evaluate()

Signature

EvaluationRequest

EvaluationContext

Example

PLAN_ONLY Mode

approveDecision()

Example

rejectDecision()

loadPolicy()

Example

Pre-Evaluation Pipeline

Post-Evaluation Hooks

Decision (v1.3 Extended)

Error Handling

Performance

Migration from v1.2

​Class

​TealEngineOptions

​evaluate()

​Signature

​EvaluationRequest

​EvaluationContext

​Example

​PLAN_ONLY Mode

​approveDecision()

​Example

​rejectDecision()

​loadPolicy()

​Example

​Pre-Evaluation Pipeline

​Post-Evaluation Hooks

​Decision (v1.3 Extended)

​Error Handling

​Performance

​Migration from v1.2

​Related Documentation

Class

TealEngineOptions

evaluate()

Signature

EvaluationRequest

EvaluationContext

Example

PLAN_ONLY Mode

approveDecision()

Example

rejectDecision()

loadPolicy()

Example

Pre-Evaluation Pipeline

Post-Evaluation Hooks

Decision (v1.3 Extended)

Error Handling

Performance

Migration from v1.2

Related Documentation