Skip to main content

​
Purpose

Reason codes provide a structured explanation for why a policy decision was taken in TealTiger. Every enforcement decision—whether allow, deny/block, or modify/degrade/redact—can emit one or more reason codes to ensure:
  • Transparency
  • Auditability
  • Debuggability
  • Enterprise trust
Reason codes bridge the gap between policy evaluation and human or system understanding.

​
Reason Code Contract (Normative)

This section is normative. TealTiger components that emit reason codes MUST follow the rules below.

​
Required presence

  • If Decision.action == ALLOW, reason_codes MAY be empty.
  • If Decision.action != ALLOW, reason_codes MUST contain at least one reason code.

​
Cardinality

  • A decision MAY emit multiple reason codes.
  • Each reason code MUST be a stable identifier (not free text).

​
Stability

  • A reason code’s meaning is immutable within v1.1.x.
  • Existing reason codes MUST NOT be reused for different semantics.
  • New reason codes MAY be added (additive evolution).
Applications should branch on Decision.action and reason_codes. They must not parse free-text messages for enforcement logic.

​
What Is a Reason Code?

A reason code is a stable, machine-readable identifier that represents a specific policy outcome or governance condition. It answers the question:
Why did this decision happen?
Rather than relying on free‑text messages, TealTiger uses reason codes to ensure consistency across:
  • SDKs
  • Runtimes
  • Logs
  • Audit systems
  • SIEM / GRC tools

​
Why Reason Codes Matter

Reason codes are critical for enterprise adoption. They enable:
  • Explainable governance outcomes
  • Deterministic policy behavior
  • Regulatory audits and evidence trails
  • Automated remediation and routing
  • User-friendly error handling
Without reason codes, policy enforcement becomes opaque and difficult to trust.

​
Reason Code Structure

TealTiger reason codes follow a predictable structure. Reason codes should follow the pattern: <DOMAIN>_<CATEGORY>_<DETAIL> Where:
  • <DOMAIN> identifies the governance domain: SEC, COST, REL
  • <CATEGORY> groups the type of control: TOOL_ACCESS, TOKEN_CLAMP, TIMEOUT, etc.
  • <DETAIL> is the stable outcome/condition label: UNTRUSTED_PROD, FREE_TIER, FALLBACK_APPLIED
This structure is designed for deterministic filtering, aggregation, and alerting. Exact naming is less important than stability and consistency.

​
Case and separators

  • Use uppercase letters and underscores for portability.
  • Avoid spaces and punctuation that complicate log querying.

​
Reason Codes Across Governance Domains

Reason codes are intentionally domain-neutral and apply uniformly across governance concerns:

​
Security governance (SEC_*)

  • Tool access restrictions
  • Prompt injection and exfiltration safeguards (expressed via explicit signals)
  • Identity and environment-based controls

​
Cost governance (COST_*)

  • Token clamps
  • Model tier downgrades
  • Budget window and quota enforcement

​
Reliability governance (REL_*)

  • Timeouts and safe fallbacks
  • Rate limits and concurrency constraints
  • Deterministic degradation under stress

​
Multiple Reason Codes (Ordering and Interpretation)

A single decision may emit multiple reason codes.

​
Ordering

  • Order MUST NOT be relied upon for program logic.
  • Consumers should treat reason_codes as an unordered set.

​
Primary vs secondary reasons

  • If a primary reason is needed, it should be represented explicitly via a dedicated field (e.g., extensions.primary_reason_code).
  • Consumers should assume all emitted codes are relevant.
If you need stable “primary reason” semantics, define it in policy design and emit it explicitly. Do not infer primacy from array position.

​
Relationship to Decision and Audit Events

  • Decision.action tells you what to do.
  • reason_codes tell you why.
  • AuditEvent records the Decision and reason codes as evidence.
Reason codes are designed to be:
  • stable across SDKs and runtimes
  • safe to export to SIEM/log stores
  • suitable for dashboards and remediation rules

​
Guidance for Policy Authors

​
1) Define reason codes as part of the policy contract

  • Every deny/modify/redact/degrade path should emit at least one reason code.
  • Prefer codes that are actionable and unambiguous.

​
2) Keep codes stable

  • Treat codes as public API.
  • If semantics change, mint a new code.

​
3) Keep codes composable

  • Use domain and category prefixes consistently.
  • Avoid embedding variable data (IDs, usernames) inside reason codes.

​
Example Reason Codes (Conceptual)

These examples illustrate style and intent. Your repository’s catalog is the source of truth.

​
Evolution Rules

  • ✅ Add new reason codes (additive)
  • ✅ Add new reason code families (additive)
  • ❌ Change meaning of an existing code
  • ❌ Reuse a code for different semantics
  • ❌ Remove a code that is still emitted in the current version line
  • /concepts/decision-model
  • /policy/conditions-and-actions
  • /policy/policy-authoring-guide
  • /policy/golden-corpus
  • /audit/audit-event-schema