Traces.

Everything on this page was produced by the real runtime: the haunted desk chain, run twice against a scripted Jev client at build time. The probabilities are hand-picked; the spans, decisions, summaries and diffs are exactly what jev.run returns.

Anatomy of a trace#

A trace is plain, versioned JSON. Save it, ship it to your logs, render it, diff it. Here's the top of the toaster run: My toaster whispers my name at 3am and the bread comes out cold.

{

  "version": 1,

  "runId": "run_7f3a9c21e04b5d18",

  "chainId": "front-desk",

  "status": "ok",

  "startedAt": "2026-09-25T03:41:46.660Z",

  "input": "My toaster whispers my name at 3am and the bread comes out cold.",

  "usage": {

    "calls": 3,

    "requests": 3,

    "inputTokens": 364,

    "outputTokens": 5,

    "costUsd": 0.000015288

  },

  "models": ["jev-1.13.0"],

  "durationMs": 143.94,

  "output": "Try turning it off and on again. If it asks you not to, call us back.",

  "spans": "[ …5 spans ]"

}

Decisions#

Route, gate and cascade spans carry a decision: the edge taken, every candidate edge with the number that decided it, the bar it was measured against, and one sentence explaining why. Here's the root span of the toaster run, trimmed a little:

{

  "path": "$",

  "nodeId": "front-desk",

  "kind": "route",

  "status": "ok",

  "start": 1.65,

  "end": 143.92,

  "input": "My toaster whispers my name at 3a…",

  "calls": [

    {

      "id": "call_1",

      "model": "jev-1.13.0",

      "state": "My toaster whispers my name at 3a…",

      "questions": {

        "decision": {

          "type": "choice",

          "instructions": "Which team should handle this app…",

          "criteria": { "repair": "…", "billing": "…", "paranormal": "…" }

        },

        "sarcastic": {

          "type": "noul",

          "instructions": "Is the customer joking or being s…"

        },

        "angry": { "type": "noul", "instructions": "Is the customer angry?" }

      },

      "answers": {

        "decision": {

          "type": "choice",

          "choice": "paranormal",

          "probabilities": { "repair": 0.02, "billing": 0.004, "paranormal": 0.976 },

          "confidence": 0.887

        },

        "sarcastic": { "type": "noul", "noul": 0.08 },

        "angry": { "type": "noul", "noul": 0.11 }

      },

      "inputTokens": 162,

      "outputTokens": 3,

      "costUsd": 0.000006804,

      "start": 2.12,

      "end": 43.5,

      "latencyMs": 38,

      "attempts": 1,

      "requestId": "req_5e1f00"

    }

  ],

  "decision": {

    "kind": "route",

    "question": "decision",

    "taken": "paranormal",

    "edges": [

      { "edge": "repair", "value": 0.02, "taken": false },

      { "edge": "billing", "value": 0.004, "taken": false },

      { "edge": "paranormal", "value": 0.976, "taken": true },

      { "edge": "lowConfidence", "value": 0.887, "taken": false }

    ],

    "metric": "probability",

    "value": 0.976,

    "confidence": 0.887,

    "summary": "Went to \"paranormal\" with 98%, a landslide over \"repair\" at 2% (confidence 0.89)."

  },

  "output": "Try turning it off and on again. …"

}

explainTrace#

explainTrace(trace) returns a short story of the run: one line per decision, plus how it ended (halted, failed or aborted). Good for logs, Slack alerts and the bottom of a support ticket.

import { explainTrace } from "jevchain";

explainTrace(trace).forEach((line) => console.log(line));

The wording scales with the margin: a lead of 0.6 or more is “a landslide”, then “a comfortable win”, “a clear lead”, “a narrow lead”, and under 0.05 “a photo finish” (marginWord). Gates say how far a value cleared or missed its bar.

diffTraces#

Same chain, two inputs, different endings. diffTraces(a, b) compares the paths they visited and names the first decision where they split. The microwave run (The microwave opened by itself, said 'soon', and now there is smoke coming out of it.) got through the front desk the same way, then failed the safety gate:

import { diffTraces } from "jevchain";

const diff = diffTraces(toaster, microwave);

{
  "shared": ["$", "$/paranormal", "$/paranormal/0"],
  "onlyA": [
    "$/paranormal/0/then",
    "$/paranormal/0/then/possessed-firmware"
  ],
  "onlyB": ["$/paranormal/0/otherwise"],
  "divergedAt": {
    "path": "$/paranormal/0",
    "nodeId": "anyone-in-danger",
    "a": "then",
    "b": "otherwise"
  }
}

Use it to explain a regression (“why did yesterday's ticket go to billing?”), or in tests: pin a golden trace and assert that divergedAt is undefined.

graphOf and overlayTrace#

A chain is a tree, but it runs like a graph: routes fan out, parallels fork and join, cascades climb a ladder. graphOf(chain) compiles it into vertices and edges, adding the synthetic ones you'd want to draw: tier vertices for each cascade rung, a join after every parallel, and a halt for gates with no otherwise. Every edge that a decision picks carries decidedBy, pointing at the span and edge key that chose it.

overlayTrace(graph, trace) paints a run onto it: each vertex gets a state (idle, running, ok, error, halted, skipped) and each edge is taken or not-taken with its deciding number. It accepts partial traces, which is how the studio animates a run as events stream in. The two runs from above, drawn by this site's own map component:

import { graphOf, overlayTrace } from "jevchain";

const graph = graphOf(hauntedDesk);           // { vertices, edges, entry }
const overlay = overlayTrace(graph, trace);    // { vertices: {id → state}, edges: {id → state, value} }

• calls jev
• your code
• leaf / emit
• fork / join