Decision Traces

A Decision Trace is the permanent, queryable record of how a specific agent-driven decision was made and executed.

Key Principle: Every decision creates a trace. The trace is the only way to answer "Why was this allowed?" later.

What Decision Traces Are

A Decision Trace is:

• An immutable, append-only record
• A complete audit trail of a single decision
• A structured timeline of events
• A snapshot of decision-time state
• The answer to "why was this allowed?"

It answers:

"What decision was made, what data was used, which policies were checked, who approved exceptions, and what changed as a result?"

What Decision Traces Are Not

A Decision Trace is not:

• A log file
• A model's chain-of-thought
• A workflow execution log
• A database transaction log
• A mutable record

It does not store full sensitive payloads by default. It stores evidence and references, not copies of data.

Key Properties

1. Execution-Time Capture

Traces are written as the decision happens, not after the fact via ETL or batch processing.

Why this matters:

• No data loss if the system crashes
• Real-time auditability
• Immediate availability for queries

2. Append-Only

Trace history is immutable. New information is recorded as new events, never by updating existing events.

Why this matters:

• Complete audit trail preserved
• No retroactive modifications
• Historical accuracy guaranteed

3. Evidence-First

A trace stores what was consulted and what was done, with references and summaries. It does not require storing full sensitive payloads.

Why this matters:

• Privacy by design
• Data minimization
• Safe for long-term retention

4. Replay-Friendly

A trace contains decision-time snapshots (policy/schema/product versions) so "why" remains explainable later, even if policies or data products change.

Why this matters:

• Historical decisions remain understandable
• Policy changes don't break audit trails
• Replay and analysis possible years later

Trace Structure

A Decision Trace is composed of four parts:

1. Decision Envelope - The identity and lifecycle of the decision
2. Decision Events - Append-only timeline of what happened
3. Decision Snapshots - Versions/hashes of what was "true" at decision time
4. Outcome Summary - Canonical result, status, and key metrics

You can think of it as:

• Envelope = what this decision is
• Events = what happened over time
• Snapshots = what "version of reality" applied
• Outcome = what the decision produced

1. Decision Envelope

The envelope is the header for the trace. It uniquely identifies the decision and provides the minimum metadata needed to find and interpret it.

Key fields:

• decision_id - Stable ID (e.g., TMEM_01JABCDEF...)
• intent - Structured label (e.g., renewal.discount.evaluate)
• automation_mode - Responsibility model (propose, approve, override, autonomous)
• actor - Who initiated the decision (e.g., renewal-agent-v1)
• status - Current lifecycle state (open, needs_approval, approved, committed, aborted, failed)
• created_at / closed_at - Lifecycle timestamps
• metadata - Optional tags for search and grouping

The envelope answers: "What decision is this?"

2. Decision Events

Decision Events are the body of the trace. Each event records one fact about what happened during the decision.

Events are append-only. You never rewrite history; you add new events.

Event Structure

Every event includes:

• event_id - Unique identifier
• decision_id - Parent decision
• timestamp - When the event occurred
• type - What kind of event (see below)
• summary - Short human-readable summary (safe, non-sensitive)
• payload - Structured details (may include references rather than raw values)

Core Event Types

Read Events

Records that the decision accessed data via a Data Product.

Stores:

• Which data_product was accessed
• Declared purpose
• Query shape (bounded, sanitized)
• Result summary (counts, IDs, ranges)
• Data product and schema hashes

Important: Stores references and summaries, not full sensitive rows by default.

Write Events

Records that a mutation was executed via a Data Product.

Stores:

• Which data_product was written to
• Declared purpose
• Mutation summary (fields touched, counts)
• Target references (IDs)
• Data product and schema hashes

Policy Evaluation Events

Records that a policy was evaluated.

Stores:

• policy_id and policy version/hash
• Input references (to prior reads, context, or parameters)
• Outcome: allow, deny, or requires_exception
• Rationale (structured + short text)
• Exception route (if applicable)

Approval Events

Records approval requests and resolutions.

Approval Requested:

• Channel (Slack, email, webhook)
• Route (channel name, email, webhook endpoint)
• Approver role/group (if known)
• Expiration time
• Request summary (safe, non-sensitive)

Approval Resolved:

• Resolution: approved, rejected, or expired
• Approver identity
• Timestamp
• Rationale (if provided)
• Conditions (optional)

Context Events

Records agent reasoning, internal facts, confidence scores, or model metadata.

Outcome Events

Records the final decision outcome.

Stores:

• Final status: committed, aborted, failed, or rejected
• Error (if failed)
• Final metrics summary

3. Decision-Time Snapshots

Snapshots make "why" durable.

The hardest problem in explaining decisions later is that reality changes:

• Schemas evolve
• Policies change
• Data products change
• Connectors move regions

A snapshot captures what versions were in effect when the decision ran.

Snapshot captures:

• Policy hashes - Exact policy versions evaluated
• Schema hashes - Schema versions used for data access
• Data product hashes - Data product versions used
• Effective restrictions - Restrictions that applied at decision time

Why this matters:

"Why this was allowed" remains answerable even years later.

Even if:

• Policies are updated
• Schemas change
• Data products are deprecated

The snapshot preserves the exact state at decision time.

Snapshots are captured immediately before commit and are never updated after commit.

4. Outcome Summary

While the outcome event is part of the event log, the outcome summary provides a fast-query "summary row" for indexing and dashboards.

Summary fields:

• decision_id, intent, actor, automation_mode
• status / outcome
• created_at / closed_at
• duration_ms
• data_products_touched
• policies_evaluated
• approvals_required (bool)
• approvals_granted (bool)
• writes_committed (bool)
• error_code / error_message (if failed)

This summary enables fast filtering without scanning all events.

How "Why Was This Allowed?" Is Answered

TraceMem answers "Why was this allowed?" by traversing the trace:

1. Find decision envelope - Identify the decision and its context
2. Find policy evaluations - See which policies were checked and their outcomes
3. If exception route - Find approval request + resolution
4. Verify snapshot versions - Confirm what versions were effective at decision time
5. Show the writes - Display what mutations were committed

This produces a deterministic explanation supported by evidence.

Example explanation:

{
  "explanation": {
    "outcome": "allowed_with_approval",
    "summary": "Decision required approval because proposed discount (20%) exceeded policy cap (10%). Approval was granted by finance team.",
    "policy_evaluations": [
      {
        "policy_id": "discount_cap_v3",
        "outcome": "requires_exception",
        "reason": "proposed_discount 0.20 exceeds cap 0.10"
      }
    ],
    "approval_resolution": {
      "status": "approved",
      "resolved_by": "slack:U12345",
      "rationale": "3 SEV-1 incidents; churn risk high."
    }
  }
}

Trace Immutability

Key principle: Traces are append-only and immutable.

• Events are never updated or deleted
• Snapshots are never modified after commit
• Historical traces remain valid even if policies/data products change
• Complete audit trail preserved forever

This immutability ensures:

• Audit integrity
• Legal compliance
• Historical accuracy
• Trust in the system

Data Minimization and Privacy

Decision traces are extremely valuable, but they can also accidentally become a copy of sensitive data if not designed carefully.

Recommended default behavior:

• Store references and summaries, not full payloads
• Store full payloads only if the Data Product explicitly allows it
• Always label events with data classifications (PII, restricted, etc.)
• Keep a clear separation between:
  • "what the agent saw" (can be sensitive)
  • "what the trace remembers" (should be safe by default)

Examples of safe summaries:

• Row counts
• IDs/hashes
• Ranges (min/max timestamps)
• Schema hashes
• Policy versions

Querying Traces

Traces can be queried in multiple ways:

By Decision Identity

When you already know the decision ID:

GET /admin/traces/{decision_id}

By Intent

To explore a class of decisions:

GET /admin/traces?intent=renewal.discount.evaluate&status=committed

By Outcome

To understand risk and behavior:

GET /admin/traces?status=aborted&from=2026-01-01T00:00:00Z

By Policy/Product/Schema Hash

For change analysis:

GET /admin/traces?policy_hash=p:3a7f...

Precedent Search

To find similar past decisions:

GET /admin/precedent?intent=renewal.discount.evaluate&policy_hash=p:3a7f...

Best Practices

1. Query by intent - Use consistent intent patterns for grouping
2. Use snapshots - Snapshots preserve decision-time state
3. Export for audit - Export traces for long-term retention
4. Search by policy/product hashes - Find decisions using specific versions
5. Use precedent search - Learn from similar past decisions
6. Respect data minimization - Don't store sensitive data unless necessary
7. Understand the timeline - Events are chronological and causal

Mental Model

The Decision Trace is the courtroom transcript.
Every piece of evidence (data read) is recorded.
Every rule checked (policy evaluation) is documented.
Every judgment (approval) is captured.
The verdict (outcome) is preserved forever.
Years later, you can still read the transcript and understand exactly what happened and why.

Relationship to Other Concepts

• Decision Envelopes - Every trace is created from a Decision Envelope
• Data Products - Every read/write event references a Data Product
• Policies - Policy evaluations are part of traces
• Approvals - Approval events are part of traces
• Connectors - Schema hashes in snapshots reference Connector schemas