TEEC — Typed Evidence & Evidence Contracts

Every governance decision in TealTiger produces a structured evidence envelope that can be validated, exported, cryptographically anchored, and independently audited. TEEC (Typed Evidence & Evidence Contract) is the formal schema that defines what a valid governance decision looks like.

TEEC v2.0.0 ships with TealTiger v1.3.0. It extends v1.0 (shipped in v1.2) with NHI identity, cryptographic proof, automation levels, control IDs, OWASP category mapping, and workload identity binding. All v1.0 fields are preserved — full backward compatibility.

Why TEEC Matters

Risk	Without TEEC	With TEEC
Audit gaps	Decisions are logged but not validated against a schema	Every decision validated against a versioned contract before emission
Non-repudiation failure	No proof that a decision was made at a specific time	Cryptographic receipts with RFC 3161 timestamping
Compliance mapping gaps	Manual effort to map decisions to control frameworks	Control IDs and OWASP categories embedded in every envelope
Identity attribution	No link between decisions and the agent that triggered them	NHI identity, workload identity, and attestation evidence in every envelope
Evidence tampering	Logs can be modified after the fact	Merkle tree inclusion proofs and governance bundle hash

Compliance alignment: SOC 2 (CC7.2 — monitoring), EU AI Act (Art. 12 — record-keeping), HIPAA (§164.312 — audit controls), NIST AI RMF (MEASURE 2.5 — AI system monitoring), ISO 42001 (A.12.4 — logging).

TEEC Registry Contents

The TEEC registry defines three catalogs:

Catalog	Count	Purpose
Reason Codes	32	Why a decision was made
Event Types	18	What happened during evaluation
Decision Actions	12	What the engine decided to do

Reason Codes (32)

Reason codes are grouped into 8 categories. Each code has a severity level and a default action.

Policy (2 codes)

Code	Severity	Default Action
`POLICY_COMPLIANT`	info	ALLOW
`POLICY_VIOLATION`	high	DENY

Content (4 codes)

Code	Severity	Default Action
`PII_DETECTED`	high	REDACT
`PROMPT_INJECTION_DETECTED`	critical	DENY
`HARMFUL_CONTENT_DETECTED`	critical	DENY
`UNSAFE_CODE_DETECTED`	high	DENY

Tool (3 codes)

Code	Severity	Default Action
`TOOL_NOT_ALLOWED`	high	DENY
`TOOL_PARAMETER_INVALID`	medium	DENY
`TOOL_RATE_LIMIT_EXCEEDED`	medium	DENY

Reliability (5 codes)

Code	Severity	Default Action
`CIRCUIT_OPEN`	high	DENY
`CIRCUIT_HALF_OPEN`	medium	DEGRADE
`RETRY_BUDGET_EXCEEDED`	high	DENY
`FALLBACK_TRIGGERED`	medium	DEGRADE
`DEGRADE_TRIGGERED`	medium	DEGRADE

Cost (5 codes)

Code	Severity	Default Action
`COST_BUDGET_EXCEEDED`	high	DENY
`COST_VELOCITY_ANOMALY`	medium	REQUIRE_APPROVAL
`COST_MODEL_TIER_VIOLATION`	medium	DEGRADE
`COST_ESTIMATED_TOO_HIGH`	medium	DENY
`MODEL_DOWNGRADED`	low	DEGRADE

Mode (2 codes)

Code	Severity	Default Action
`MONITOR_MODE_VIOLATION`	info	ALLOW
`REPORT_ONLY_MODE`	info	ALLOW

Secrets (5 codes) — New in v1.2

Code	Severity	Default Action
`SECRET_DETECTED`	critical	DENY
`CREDENTIAL_LEAKAGE`	critical	DENY
`CREDENTIAL_TTL_EXCEEDED`	high	DENY
`CREDENTIAL_ROTATION_REQUIRED`	medium	REQUIRE_APPROVAL
`SECRET_SCAN_SKIPPED_PERF_BUDGET`	medium	DEGRADE

Memory (6 codes) — New in v1.2

Code	Severity	Default Action
`MEMORY_WRITE_DENIED_SECRET`	critical	DENY_WRITE
`MEMORY_WRITE_DENIED_PII`	high	DENY_WRITE
`MEMORY_WRITE_REDACTED`	medium	REDACT_AND_WRITE
`MEMORY_WRITE_SUMMARY_ONLY`	medium	STORE_SUMMARY_ONLY
`MEMORY_SCOPE_VIOLATION`	high	DENY_READ
`MEMORY_READ_DENIED_CLASSIFICATION`	high	DENY_READ

Event Types (18)

Event types describe what happened during governance evaluation. Each event is associated with a module.

Event Type	Description	Module
`policy.evaluation`	Policy evaluated against request	core
`policy.violation`	Policy violation detected	core
`tool.evaluation`	Tool usage evaluated	core
`content.moderation`	Content moderation check	guard
`pii.detection`	PII detection scan	guard
`prompt.injection`	Prompt injection detection	guard
`secret.detection`	Secret detection scan	secrets
`credential.ttl`	Credential TTL enforcement	secrets
`memory.write`	Memory write governance	memory
`memory.read`	Memory read governance	memory
`memory.retention`	Memory retention governance	memory
`reliability.retry`	Retry attempt	reliability
`reliability.fallback`	Fallback activation	reliability
`reliability.degrade`	Degradation activation	reliability
`reliability.circuit`	Circuit breaker state change	reliability
`cost.budget`	Cost budget evaluation	monitor
`registry.lookup`	Registry catalog lookup	registry
`audit.event`	Audit event emitted	audit

Decision Actions (12)

TealTiger v1.2 supports 12 decision actions — the 6 from v1.1 plus 5 new memory-governance actions, plus ALLOW_WRITE which is distinct from ALLOW in the memory dimension.

v1.1 Actions (6)

Action	Description	Dimensions
`ALLOW`	Allow the operation to proceed	all
`DENY`	Deny the operation	all
`REDACT`	Redact sensitive content before proceeding	security, content
`DEGRADE`	Degrade service quality	cost, reliability
`REQUIRE_APPROVAL`	Require manual approval	all
`TRANSFORM`	Transform content before proceeding	security, content

v1.2 Memory Actions (6) — New

Action	Description	Dimensions
`ALLOW_WRITE`	Allow memory write	memory
`DENY_WRITE`	Deny memory write	memory
`REDACT_AND_WRITE`	Redact then write to memory	memory
`STORE_SUMMARY_ONLY`	Store summary-only representation	memory
`DENY_READ`	Deny memory read	memory

Evidence Envelope Structure

Every Decision returned by TealEngine includes TEEC fields. v2.0.0 extends the envelope with identity, proof, and compliance fields:

interface TEECEnvelopeV2 {
  // Core fields (v1.0 — 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;
  event_type: string;
  teec_version: string;        // "2.0.0"
  timestamp: number;
  module: string;

  // v2.0.0 — Identity & Attribution
  nhi_identity?: {
    agent_id: string;
    owner: string;
    classification: string;
    attestation_method: string;
    lifecycle_state: 'active' | 'suspended' | 'revoked';
  };
  workload_identity?: {
    platform: string;           // 'k8s' | 'ecs' | 'lambda' | 'aci' | 'cloud-run'
    app_id: string;
    environment: string;
    tenant_id?: string;
  };

  // v2.0.0 — Cryptographic Proof
  proof?: {
    decision_hash: string;      // SHA-256
    merkle_root: string;
    merkle_proof: string[];     // Sibling hashes
    prev_hash: string;          // Chain linkage
    anchor_ref?: string;        // RFC 3161 TSA reference
  };

  // v2.0.0 — Automation & Control
  automation_level: 'auto_allow' | 'auto_deny' | 'auto_sanitize' | 'approval_required';
  control_id?: string;          // e.g., "SEC-001", "NHI-003"
  owasp_category?: string;      // e.g., "ASI-07"
  governance_bundle_hash?: string;

  // v2.0.0 — Cost Evidence
  cost_evidence?: {
    input_tokens: number;
    output_tokens: number;
    reasoning_tokens?: number;
    estimated_cost_usd: number;
    model: string;
    provider: string;
  };

  // v2.0.0 — Verification
  verification_level?: 'LEVEL_1_INTEGRITY' | 'LEVEL_2_SUFFICIENCY' | 'LEVEL_3_APPROPRIATENESS';
  provenance?: {
    source_class: string;
    trust_tier: number;
    lineage: string[];
  };

  metadata: {
    evaluation_time_ms: number;
    modules_evaluated: string[];
    modules_failed: string[];
    teec_warnings?: object[];
    pre_evaluation?: {
      freeze_checked: boolean;
      nhi_verified: boolean;
      scope_checked: boolean;
      temporal_checked: boolean;
    };
  };
}

TEEC v2.0.0 is backward-compatible with v1.0. All v1.0 fields retain their semantics. New fields are optional — they appear only when the corresponding v1.3 feature is configured.

TEEC Validation

The TEECValidator checks every decision before it leaves the engine:

Reason codes — Are all codes registered in the TEEC catalog?
Event type — Is the event type registered?
Decision action — Is the action registered?
Required fields — Are correlation_id, timestamp, and teec_version present?

Validation is non-blocking — invalid fields produce warnings in metadata.teec_warnings rather than failing the request.

const validator = engine.getTEECValidator();
const results = validator.validateDecision(decision);

for (const result of results) {
  if (!result.valid) {
    console.warn(`TEEC warning: ${result.field} — ${result.message}`);
  }
}

Exporting Evidence

TealTiger v1.2 supports three export formats for compliance reporting:

SARIF v2.1.0

Static Analysis Results Interchange Format — integrates with GitHub Code Scanning, Azure DevOps, and other SARIF consumers.

import { BundleExporter } from 'tealtiger';

const exporter = new BundleExporter();
const sarif = exporter.toSARIF(decisions);
fs.writeFileSync('governance-report.sarif', JSON.stringify(sarif, null, 2));

JUnit XML

For CI/CD pipelines — each decision becomes a test case, denials become failures.

const junit = exporter.toJUnitXML(decisions);
fs.writeFileSync('governance-report.xml', junit);

JSON

Raw evidence export for custom processing.

const json = exporter.toJSON(decisions);
fs.writeFileSync('governance-report.json', JSON.stringify(json, null, 2));

Use SARIF for security tooling integration, JUnit XML for CI/CD gates, and JSON for custom dashboards or data pipelines.

Loading the Registry

The TEEC registry is embedded in the SDK. No file I/O or network calls needed.

import { TEECRegistryLoader } from 'tealtiger';

const registry = TEECRegistryLoader.loadEmbedded();

console.log(registry.version);                    // "2.0.0"
console.log(registry.reason_codes.size);           // 60+
console.log(registry.event_types.size);            // 30+
console.log(registry.decision_actions.size);       // 16

You can also inspect individual entries:

const code = registry.reason_codes.get('NHI_SCOPE_VIOLATION');
// { code: 'NHI_SCOPE_VIOLATION', title: 'Agent scope violation',
//   category: 'identity', severity: 'high',
//   default_action: 'DENY', control_id: 'NHI-003',
//   owasp: 'ASI-07', tags: ['nhi', 'access-control'] }

TealEngine v1.3 API — Engine that produces TEEC envelopes
TealProof — Cryptographic proof layer
SOC/IR Pipeline — SIEM export of TEEC evidence
NHI Governance — Identity fields in TEEC
Decision Lifecycle — How decisions flow through the engine
v1.3.0 Release Notes — Full changelog

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

TEEC — Typed Evidence & Evidence Contracts

Why TEEC Matters

TEEC Registry Contents

Reason Codes (32)

Policy (2 codes)

Content (4 codes)

Tool (3 codes)

Reliability (5 codes)

Cost (5 codes)

Mode (2 codes)

Secrets (5 codes) — New in v1.2

Memory (6 codes) — New in v1.2

Event Types (18)

Decision Actions (12)

v1.1 Actions (6)

v1.2 Memory Actions (6) — New

Evidence Envelope Structure

TEEC Validation

Exporting Evidence

SARIF v2.1.0

JUnit XML

JSON

Loading the Registry

​Why TEEC Matters

​TEEC Registry Contents

​Reason Codes (32)

​Policy (2 codes)

​Content (4 codes)

​Tool (3 codes)

​Reliability (5 codes)

​Cost (5 codes)

​Mode (2 codes)

​Secrets (5 codes) — New in v1.2

​Memory (6 codes) — New in v1.2

​Event Types (18)

​Decision Actions (12)

​v1.1 Actions (6)

​v1.2 Memory Actions (6) — New

​Evidence Envelope Structure

​TEEC Validation

​Exporting Evidence

​SARIF v2.1.0

​JUnit XML

​JSON

​Loading the Registry

​Related Documentation

Why TEEC Matters

TEEC Registry Contents

Reason Codes (32)

Policy (2 codes)

Content (4 codes)

Tool (3 codes)

Reliability (5 codes)

Cost (5 codes)

Mode (2 codes)

Secrets (5 codes) — New in v1.2

Memory (6 codes) — New in v1.2

Event Types (18)

Decision Actions (12)

v1.1 Actions (6)

v1.2 Memory Actions (6) — New

Evidence Envelope Structure

TEEC Validation

Exporting Evidence

SARIF v2.1.0

JUnit XML

JSON

Loading the Registry

Related Documentation