IX trace output is JSON produced by:
ix trace file.ix
or embedded inside evidence bundles produced by:
ix evidence file.ix --out evidence-dir
The trace is meant to show what the IX runtime did during one execution.
ix trace emits a JSON object with this general shape:
{
"status": "completed",
"variables": {},
"memory": {},
"outputs": [],
"replies": [],
"approvals_required": [],
"policies": [],
"tool_results": [],
"handoffs": [],
"branches": [],
"trace": []
}
Current expected success status:
"completed"
If execution fails, the CLI returns non-zero and prints the error to stderr instead of producing a completed JSON payload.
Local variables visible at the end of execution.
Example:
{
"name": "IX"
}
Runtime memory values recorded through remember.
Example:
{
"mission": "traceable behavior"
}
Values emitted through print.
[
"Diagnostic output"
]
Values emitted through reply.
[
"Hello from IX"
]
Human approval markers created by:
require human_approval reason "Reviewer must approve before use"
Example:
[
"Reviewer must approve before use"
]
Policies recorded during execution.
Example:
[
{
"effect": "allow",
"target": "tool.upper",
"reason": "Safe deterministic built-in tool"
}
]
Tool execution records.
Example:
[
{
"tool": "tool.upper",
"output_name": "shouted",
"result": "HELLO",
"arguments": {
"text": "hello"
},
"policy": {
"effect": "allow",
"target": "tool.upper",
"reason": "\"Safe deterministic built-in tool\""
}
}
]
Tool calls are denied unless an explicit allow policy matches.
Agent-to-agent handoff records.
Example:
[
{
"target_agent": "Reviewer",
"target_event": "review",
"arguments": {
"item": "request"
},
"output_name": "verdict",
"output_value": "approved: request",
"replies": [
"approved: request"
],
"outputs": []
}
]
Conditional branch records.
Example:
[
{
"condition": "score >= 80",
"selected_branch": "then",
"condition_value": true,
"statement_count": 1
}
]
A list of ordered trace events.
Each event has this shape:
{
"step": 1,
"kind": "run.start",
"message": "IX execution started",
"source": {
"filename": "examples/hello.ix",
"line": 1,
"column": 1
},
"data": {}
}
Sequential event number starting at 1.
Machine-readable event kind.
Human-readable event message.
Source location for the construct that produced the event.
Event-specific payload.
Runtime execution started.
Runtime execution completed.
A variable was set.
A memory value was stored.
A memory value was recalled.
A printed output was emitted.
A reply was emitted.
An assertion was evaluated.
Data includes:
{
"expression": "score >= 0",
"passed": true
}
A domain-specific trace marker from an IX trace statement.
A human approval requirement was recorded.
A policy statement was recorded during execution.
A tool call was denied by policy.
This event is emitted before the runtime fails closed.
A tool call executed.
Data includes:
{
"tool": "tool.upper",
"output_name": "shouted",
"tool_result": "HELLO",
"arguments": {
"text": "hello"
},
"policy": {
"effect": "allow",
"target": "tool.upper",
"reason": "\"Safe deterministic built-in tool\""
}
}
An agent handoff started.
An agent handoff completed.
A conditional branch was evaluated.
Data includes:
{
"condition": "score >= 80",
"selected_branch": "then",
"condition_value": true,
"statement_count": 1
}
This schema is stable enough for local review and tests, but the project is still experimental. Treat this as the current canonical trace schema, not a formal external standard.