Architecture Decision Trace is built on principles of immutability, schema safety, and failure isolation. 1. Append-Only Ledger The fundamental storage model is an Append-Only Ledger. Decisions are recorded as a stream of immutable events (start, evidence, outcome). You cannot “update” a decision; you can only append new information. This ensures a tamper-evident audit trail. Even if a process crashes or is interrupted, the partial history is preserved. 2. Schema-First Philosophy Data quality is paramount for decision analysis and auditing. ...
Decision-Traces
Core Concepts What is a Decision? A Decision is a discrete unit of system reasoning. Unlike a log line (which says what happened) or a trace span (which says how long it took), a Decision captures why something happened. Decisions occur in: AI agents payment authorization flows fraud and risk engines approval workflows compliance systems underwriting and policy engines It is a structured event containing: Context: Who made the decision (Actor) and where (Decision Type). Input: The data used to make the decision (Evidence). Logic: The rules applied (Policy Checks). Outcome: The final result (Outcome/Action). Logs vs. Traces vs. Decisions Type Question Answered Example Log What happened? INFO: processing order #123 Trace How long did it take? span: process_order (200ms) Decision Why did we do it? “Approved order #123 because risk_score < 10” Decision Trace complements your observability stack. It doesn’t replace Logs or OpenTelemetry; it adds a semantic layer for governance and reasoning. ...
Decision Analytics Architecture Guide Turning decision traces into analytical systems Recording decision graphs is only the beginning. The long-term value of the Decision Trace SDK emerges when decision data is treated as a first-class analytical dataset: a structured record of reasoning that can be queried, aggregated, replayed, and modeled. Most analytics systems are built around events, transactions, and metrics. Decision Trace introduces a different category of data. Instead of recording what happened, it records why it happened. This shift has architectural implications. It requires thinking of decisions not as logs, but as causal artifacts that can support debugging, governance, and intelligence systems. ...
Advanced Adoption Guide Scaling the Decision Trace SDK in Production Systems The Decision Trace SDK is intentionally lightweight. You can start with a single script and grow into a distributed system without changing the mental model. The same primitives that work in local development extend naturally into production environments. This guide focuses on: scaling patterns production best practices OpenTelemetry integration governance-friendly design collector architecture organizational rollout The goal is simple: ...
Migration & Adoption Guide Adopting Decision Trace does not require a “big bang” rewrite. We recommend an incremental “Dual-Write” strategy. 1. Dual-Write Strategy You likely already have logging. Keep it. Add Decision Trace alongside your existing logging for critical “Fork in the Road” moments. Existing Code: logger.info(f"Checking score for user {user_id}") if score > 700: logger.info("Approved") return True else: logger.info("Denied") return False With Decision Trace: logger.info(f"Checking score for user {user_id}") with decision("loan.approval", actor=SYSTEM) as d: d.evidence("score", score) # Structured capture if score > 700: logger.info("Approved") d.policy_check("min_score_700", "pass") d.outcome("approved") return True else: logger.info("Denied") d.policy_check("min_score_700", "fail") d.outcome("denied") return False This allows you to verify the decision graph without disrupting existing observability dashboards. ...
Safety & Privacy Guarantees Decision Trace is designed for production use in sensitive environments. We provide strict guarantees around data integrity, availability, and privacy. 1. Evidence Integrity (Snapshotting) Rule: Modifying an object after passing it to the tracer must not change the recorded history. Mechanism: The SDK performs a deepcopy of all dictionaries and lists passed to evidence() or action() at the moment of capture. Why? To prevent race conditions where a mutable object is modified by business logic before the async exporter writes it to disk. Guarantee: The ledger reflects the exact state of the object when d.evidence() was called. 2. Failure Isolation Rule: Determining why something happened is secondary to making it happen. ...
Decision Trace V1.1 — Adoption Polish Release Status: Implementation-ready Scope: Developer experience, examples, and integration accelerators Compatibility: Fully backward-compatible with V1 schema and architecture 0. Purpose V1.1 is an adoption-focused release. It introduces no architectural changes to Decision Trace. The schema, append-only model, and core tracer semantics remain unchanged. The goal is to: deliver a 5-minute “dopamine demo” provide flagship examples that teach the mental model reduce friction for agent builders via integration adapters V1.1 optimizes first contact with Decision Trace. ...
🚀 Your First Decision Graph A hands-on tutorial with the Decision Trace SDK Modern systems don’t just produce outputs — they make decisions. Refund approvals. Risk scoring. Feature flags. AI tool selection. Behind every outcome is a chain of reasoning. Most systems throw that reasoning away. The Decision Trace SDK is built around a simple idea: Decisions should be observable, inspectable, and composable. In this tutorial, you’ll build your first decision graph — not just log events, but model real reasoning as a structured trace. ...