Stability Guarantees

TealTiger makes specific promises about what stays stable across versions. This page documents the stability contract for the entire v1.x line (v1.1 through v1.3 and beyond).

Applies to: All v1.x releases (v1.1.0, v1.1.1, v1.2.0, v1.3.0) Core promise: Existing behavior never changes within v1.x. New features are additive. Breaking changes require v2.0.

Core Stability Promises

Promise	What It Means	Since
Deterministic decisions	Same input + same policy version = same decision	v1.1
Immutable identifiers	`stable_id` values never change meaning or get reused	v1.1
Stable audit schema	Required fields and types don’t change; new fields are optional	v1.1
Reason code permanence	Existing codes keep their meaning; new codes can be added	v1.1
TEEC backward compatibility	v1.0 envelope fields preserved in v2.0 with same semantics	v1.2
FREEZE rule immutability	FREEZE rules cannot be modified, disabled, or removed by any code path	v1.3
Evaluation pipeline order	Pre-evaluation stages execute in documented order	v1.3
Bundle signature contract	Signed bundles accepted; unsigned bundles rejected (when verification enabled)	v1.3

Stability Levels

Immutable (Never Changes)

These are permanent and will never change meaning:

Audit schema identity ([email protected])
Stable document IDs (stable_id fields)
FREEZE rule IDs (once set, permanent)
TEEC envelope field names and types
Governance Event Schema field names

Stable Within v1.x (Additive Only)

These can grow but existing behavior won’t change:

Policy evaluation semantics
Decision action types (ALLOW, DENY, MODIFY, PENDING)
Reason code meanings
Risk score calculation (0-100 scale)
Automation level behavior (auto_allow, auto_deny, auto_sanitize, approval_required)
Pre-evaluation pipeline order (FREEZE → NHI → Scope → JIT → Temporal)

Expandable (Can Grow)

These catalogs expand with each release:

Reason code catalog (32 in v1.2 → 60+ in v1.3)
Event type catalog (18 in v1.2 → 30+ in v1.3)
Decision action catalog (12 in v1.2 → 16 in v1.3)
Governance domains (6 in v1.2 → 10 in v1.3)
Provider list (7 in v1.1 → 12 in v1.3)

Experimental (May Change)

Features marked experimental can change between minor versions. Currently no features are marked experimental in v1.3.

Version Compatibility Matrix

Upgrading From	Upgrading To	Breaking Changes	Migration Effort
v1.1.x	v1.2.0	None	Drop-in replacement
v1.2.x	v1.3.0	None	Drop-in replacement
v1.1.x	v1.3.0	None	Drop-in replacement

Key guarantee: evaluateV12() is preserved in v1.3. Existing v1.2 code works without modification. New v1.3 features are opt-in via the new evaluate() method.

What’s Guaranteed Across All v1.x

Deterministic Decisions

// This produces identical results in v1.1, v1.2, and v1.3
const decision1 = await engine.evaluate(request, ctx);
const decision2 = await engine.evaluate(request, ctx);
// decision1.action === decision2.action (always)
// decision1.reason_codes === decision2.reason_codes (always)

Backward-Compatible API

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

// v1.3 adds new evaluate() — doesn't break existing code
const decision = await engine.evaluate(request, ctx);

Stable Evidence Format

{
  "action": "DENY",
  "reason_codes": ["COST_BUDGET_EXCEEDED"],
  "risk_score": 85,
  "correlation_id": "req-abc123",
  "timestamp": 1716000000000,
  "teec_version": "2.0.0",
  "policy_version": "3.2.0"
}

All fields present in v1.1 evidence are preserved in v1.3. New fields (like automation_level, nhi_identity, proof) are additive.

What Can Change in v1.x (Non-Breaking)

Change Type	Example	Impact
New optional evidence fields	`nhi_identity`, `proof`, `cost_evidence` added in v1.3	None — existing parsers ignore unknown fields
New reason codes	`NHI_SCOPE_VIOLATION`, `FREEZE_BLOCK` added in v1.3	None — new codes only appear with new features
New modules	TealProof, TealFlow, TealDrift added in v1.3	None — opt-in only
New automation levels	`approval_required` added in v1.3	None — only returned when configured
Performance improvements	Faster evaluation	None — same results, less time
New providers	DeepSeek, Groq, Together, xAI, HuggingFace added in v1.3	None — existing providers unchanged

What Cannot Change in v1.x (Forbidden)

Forbidden Change	Why
Changing decision outcomes for same input	Breaks determinism guarantee
Removing required audit fields	Breaks existing parsers and SIEM integrations
Changing reason code meanings	Breaks automation built on specific codes
Reusing stable IDs for different semantics	Breaks referential integrity
Removing `evaluateV12()`	Breaks existing v1.2 code
Changing FREEZE rule behavior	Breaks safety guarantees
Weakening anti-tamper controls	Breaks separation of duties

How We Handle Future Breaking Changes (v2.0)

When v2.0 eventually ships:

12-month deprecation period — v1.x supported for 12 months after v2.0
Migration guide — Step-by-step upgrade documentation
Parallel support — Both APIs work during transition
Security patches — v1.x receives security fixes for 18 months
No surprise removals — Deprecation warnings appear at least one minor version before removal

v1.3.0 Release Notes

What’s new in the latest release

Migration Guide v1.3

Upgrade from v1.2 to v1.3

TEEC Evidence Contract

Evidence envelope schema and versioning

Product Roadmap

Future plans and timeline

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Core Stability Promises

Stability Levels

Immutable (Never Changes)

Stable Within v1.x (Additive Only)

Expandable (Can Grow)

Experimental (May Change)

Version Compatibility Matrix

What’s Guaranteed Across All v1.x

Deterministic Decisions

Backward-Compatible API

Stable Evidence Format

What Can Change in v1.x (Non-Breaking)

What Cannot Change in v1.x (Forbidden)

How We Handle Future Breaking Changes (v2.0)

v1.3.0 Release Notes

Migration Guide v1.3

TEEC Evidence Contract

Product Roadmap

​Core Stability Promises

​Stability Levels

​Immutable (Never Changes)

​Stable Within v1.x (Additive Only)

​Expandable (Can Grow)

​Experimental (May Change)

​Version Compatibility Matrix

​What’s Guaranteed Across All v1.x

​Deterministic Decisions

​Backward-Compatible API

​Stable Evidence Format

​What Can Change in v1.x (Non-Breaking)

​What Cannot Change in v1.x (Forbidden)

​How We Handle Future Breaking Changes (v2.0)

​Related Documentation

v1.3.0 Release Notes

Migration Guide v1.3

TEEC Evidence Contract

Product Roadmap

Core Stability Promises

Stability Levels

Immutable (Never Changes)

Stable Within v1.x (Additive Only)

Expandable (Can Grow)

Experimental (May Change)

Version Compatibility Matrix

What’s Guaranteed Across All v1.x

Deterministic Decisions

Backward-Compatible API

Stable Evidence Format

What Can Change in v1.x (Non-Breaking)

What Cannot Change in v1.x (Forbidden)

How We Handle Future Breaking Changes (v2.0)

Related Documentation