Decision Envelopes

A Decision Envelope is the execution boundary for every agent-initiated decision in TraceMem.

Key Principle: If an action is not executed inside a Decision Envelope, it does not exist as a decision and must not be allowed to affect reality.

What Decision Envelopes Are

A Decision Envelope is:

• A required execution context
• A lifecycle container for a single decision
• The root object for all decision traces
• The unit of auditability and replay

It answers:

"What decision is being made, by whom, under what responsibility model, and what happened as a result?"

What Decision Envelopes Are Not

A Decision Envelope is not:

• A transaction manager
• A workflow engine
• A retry mechanism
• A background job
• A UI construct

It does not do work itself. It bounds and records work done inside it.

Required Fields

Every Decision Envelope must declare the following at creation:

1. Intent (required)

A structured, human-meaningful label describing why this decision exists.

Examples:

• renewal.discount.evaluate
• support.escalation.route
• crm.account.update

Rules:

• Must be non-empty
• Must be stable across similar decisions
• Used for search, grouping, and precedent

2. Automation Mode (required)

Declares who is responsible for the outcome.

Allowed values:

• propose — agent proposes, human decides
• approve — agent executes after approval
• override — human overrides policy
• autonomous — agent executes without human approval

Automation mode is immutable once set.

3. Actor

Identifies the agent or service initiating the decision.

Examples:

• renewal-agent-v1
• support-triage-agent
• batch-job-42

This is not necessarily the approver.

4. Optional Metadata

Lightweight, non-sensitive tags for search and grouping.

Example:

{
  "account_id": "A-123",
  "opportunity_id": "O-55",
  "region": "eu"
}

Lifecycle States

State Descriptions

1. open - Envelope created and active

   • Allowed: reads, policy evaluations, approval requests, writes (subject to policy/approval)
   • Not allowed: committing outcome yet

2. needs_approval - Decision cannot proceed automatically

   • Entered when: policy returns requires_exception or automation_mode requires approval
   • Allowed: approval resolution (approve/reject)
   • Not allowed: further writes

3. approved - Required approval has been granted

   • Allowed: writes, final commit
   • Approval details already recorded as decision events

4. rejected - Required approval was explicitly rejected

   • Terminal state
   • Decision must abort

5. committed - Decision completed successfully (terminal)

   • All required policies passed or were overridden
   • All required approvals were granted
   • All writes were executed
   • Snapshots were captured
   • No further events may be added

6. aborted - Decision intentionally stopped (terminal)

   • Common causes: policy denial, approval rejection, validation failure
   • Abort still produces a complete trace

7. failed - Decision could not complete due to error (terminal)

   • Examples: backend crash, connector failure, timeout
   • Failures are recorded explicitly

State Transition Rules

Once terminal, the envelope is immutable.

Decision-Time Snapshots

Snapshots are captured immediately before commit.

They record:

• Policy versions/hashes
• Schema hashes
• Data product hashes
• Effective restrictions

Snapshots ensure that:

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

Snapshots are never updated after commit.

Error Handling

SDK-Side Errors

• Missing intent
• Missing automation_mode
• Missing purpose

→ The envelope never opens
→ No trace is created

Runtime Policy Denial

• Policy returns deny

→ Envelope transitions to aborted
→ Policy evaluation event is recorded

Approval Rejection

• Human explicitly rejects

→ Envelope transitions to rejected
→ Rejection rationale is recorded

Backend Failure

• Crash or timeout before commit

→ Envelope transitions to failed
→ Partial events are preserved
→ No commit occurs

TraceMem prefers recorded failure over silent rollback.

Best Practices

1. Always close decisions - Commit or abort explicitly
2. One decision per envelope - Don't reuse envelopes
3. Open when ready to act - Don't open too early
4. Don't hide failures - Abort or fail explicitly
5. Use meaningful intents - Follow hierarchical patterns (e.g., customer.order.create)
6. Track instances - Include instance identifiers for debugging

Mental Model

The Decision Envelope is the courtroom.
Evidence (data) is presented.
Rules (policies) are applied.
Judgment (approval or autonomy) is rendered.
The verdict (outcome) is recorded forever.