Technical Architecture

What is a trace artifact in Traverse?

A trace artifact is the structured record Traverse produces for every capability execution. It answers the question: what exactly happened, and why?

Every field in a trace artifact is populated by the runtime during execution. Nothing is added after the fact. The artifact is written when the execution reaches a terminal state — either completed or error.

What a trace artifact contains

  • trace_id — a unique identifier for this specific execution
  • capability — the name and version of the capability that was selected
  • selection_reason — why this capability was chosen over others in the registry
  • inputs — the exact inputs that were validated before execution
  • constraint_evaluation — the result of each precondition check
  • execution_path — each state transition the machine went through
  • events_emitted — all output events published during the emitting_events state
  • duration_ms — total wall time from request to terminal state
  • status — completed or error, with reason if error

Example structure

{ "trace_id": "trc_01j9...", "capability": "plan-expedition@0.2.0", "status": "completed", "duration_ms": 3, "inputs": { "destination": "Dolomites", "days": 7 }, "constraint_evaluation": { "passed": true, "checks": [] }, "events_emitted": ["expedition-planned"], "execution_path": [ "idle", "loading_registry", "ready", "discovering", "evaluating_constraints", "selecting", "executing", "emitting_events", "completed" ] }

Why trace artifacts matter

Three use cases stand out.

Debugging. When something fails, the trace tells you which state it failed in, what inputs were present, and what the constraint evaluation returned. You do not need to reproduce the failure.

Compliance auditing. In regulated domains like fintech or healthcare, you need a durable record of what ran, when, and on what inputs. Trace artifacts are queryable JSON. They can feed into a compliance store without extra instrumentation.

AI agent transparency. When an AI agent calls Traverse via the MCP server, the trace artifact records exactly what the agent asked for and what the runtime decided. This is the accountability layer that pure LLM tool calls lack.