Turn And Effect Contracts

A Jidoka turn is a pure data pipeline. The runtime compiles a Jidoka.Agent.Spec into a Jidoka.Turn.Plan, threads a Jidoka.Turn.State through Runic, and mediates external work through Jidoka.Effect.Intent/Jidoka.Effect.Result pairs. This guide documents every data contract on that path so that custom harnesses, traces, and storage layers can interoperate with the runtime without guessing.

When To Use This

• Use this guide when you are building a custom harness, sidecar, or trace exporter and need the on-the-wire shape of turn state and effects.
• Use this guide when reading a snapshot or journal in tests and needing to decode each field.
• Do not use this guide as a runtime walkthrough. See Runtime And Harness for the execution model.

Prerequisites

• You have read Agent Spec Contract.
• You can build and run a Jidoka turn (see Getting Started).

Quick Example

A turn round-trip produces every contract this guide describes.

alias Jidoka.{Agent, Turn, Effect}

spec = MyApp.TimeAgent.spec()
{:ok, plan} = Turn.Plan.new(spec)
{:ok, request} = Turn.Request.from_input("What time is it in Chicago?")

llm = fn _intent, _journal ->
  {:ok, %{type: :final, content: "Chicago time is 09:30."}}
end

{:ok, result} = MyApp.TimeAgent.run_turn(request.input, llm: llm)

result.content              #=> "Chicago time is 09:30."
result.journal              #=> %Jidoka.Effect.Journal{intents: %{...}, results: %{...}}
hd(result.events).type      #=> :turn_started (or similar)

plan, request, the in-flight Turn.State, the Turn.Result, and the Effect.Journal are all addressable, inspectable values.

Concepts

╭──────────────╮     ╭───────────────╮     ╭──────────────╮
│  Agent.Spec  │────▶│   Turn.Plan   │────▶│  Turn.State  │
╰──────────────╯     ╰───────────────╯     ╰──────┬───────╯
                                                  │ pending_effects
                                                  ▼
                                          ╭───────────────╮
                                          │ Effect.Intent │
                                          ╰──────┬────────╯
                                                 │ capability
                                                 ▼
                                          ╭───────────────╮
                                          │ Effect.Result │
                                          ╰──────┬────────╯
                                                 │ journal
                                                 ▼
                                          ╭───────────────╮
                                          │ Turn.Result   │
                                          ╰───────────────╯

Three rules anchor the model:

1. The plan is derived from the spec; the state is derived from the plan plus a request.
2. The harness only ever produces effects through Effect.Intent and consumes them through Effect.Result. The journal records both.
3. The final Turn.Result is projected from the terminal Turn.State.

Fields

Jidoka.Turn.Plan

Compiled execution defaults for one turn.

Built by Jidoka.Turn.Plan.new/1 which also runs Spec.validate_operation_policies/1 before returning.

Jidoka.Turn.Request

Input envelope for one turn.

Turn.Request.from_input/2 accepts a string, map, or keyword list and fills in defaults.

Jidoka.Turn.State

Ephemeral value threaded through the workflow.

Mutations go through Jidoka.Turn.Transition.

Jidoka.Turn.Transition

A pure transition value: new state plus pending events and diagnostics.

Transition.event/3 builds a Jidoka.Event with stable sequence ordering. Transition.commit/1 folds events and diagnostics back into the state.

Jidoka.Turn.Cursor

A pointer to the next safe resume boundary.

Constructors after_prompt/0, before_effect/1, review/1 produce the common cursor shapes.

Jidoka.Turn.Result

Final app-facing value.

Produced by Jidoka.Turn.Result.from_turn_state!/1 once status reaches :finished.

When the LLM capability is backed by ReqLLM, usage contains normalized token and cost fields when the provider returns them:

result.usage
#=> %{
#=>   llm_calls: 2,
#=>   input_tokens: 800,
#=>   output_tokens: 240,
#=>   total_tokens: 1040,
#=>   reasoning_tokens: 0,
#=>   total_cost: 0.00048
#=> }

Per-call usage remains available in the journal:

result.journal.results[effect_id].metadata.usage

Jidoka.Effect.Intent

Data description of an external effect.

Build with Effect.Intent.new/3 (kind + payload + opts) or Intent.new/1 (full map).

Jidoka.Effect.Result

Normalized result of one interpreted effect.

Effect.Result.ok/2, Effect.Result.ok/3, Effect.Result.error/2, and Effect.Result.error/3 are the convenience constructors. The third argument accepts metadata: for capability-owned metadata such as LLM usage.

Jidoka.Effect.Journal

Replay log keyed by intent id.

Use Journal.put_intent/2 and Journal.put_result/2 to extend. Use Journal.result_for/2 to ask "has this intent already been satisfied?" - the basis of replay safety.

Jidoka.Effect.OperationRequest And Jidoka.Effect.OperationResult

Typed payload/observation pair for operation effects.

OperationResult.from_effect/2 is the canonical bridge from an Intent + capability output to a durable observation.

Jidoka.Effect.LLMDecision

Constrained JSON decision protocol returned by every LLM capability.

LLMDecision.final/2 and LLMDecision.operation/3 are the two builder helpers. Capabilities may return either an LLMDecision struct or a map that LLMDecision.from_input/1 accepts.

Common Patterns

• Treat Effect.Intent.id as the only identity that matters. The journal, cursor metadata, and Effect.Result.intent_id all key off it.
• Decide once, observe once. An LLM decision returns one Intent; that intent's result is the only payload the runtime trusts.
• Use the cursor for resume boundaries, not the state. A cursor is small, serializable, and stable across versions; the state can carry rich data.
• Prefer LLMDecision structs in fake LLMs. Returning a map works (the runtime calls LLMDecision.from_input/1), but a struct catches typos sooner.

Testing

A deterministic test asserts on the journal, not on the prompt.

test "operation effect is recorded once" do
  llm = fn _intent, journal ->
    case map_size(journal.results) do
      0 -> {:ok, Jidoka.Effect.LLMDecision.operation("local_time", %{"city" => "Chicago"})}
      _ -> {:ok, Jidoka.Effect.LLMDecision.final("Chicago time is 09:30.")}
    end
  end

  {:ok, result} = MyApp.TimeAgent.run_turn("What time is it in Chicago?", llm: llm)

  operation_results =
    result.journal.results
    |> Map.values()
    |> Enum.filter(&(&1.kind == :operation))

  assert length(operation_results) == 1
end

Troubleshooting

Reference

• Jidoka.Turn.Plan
• Jidoka.Turn.Request
• Jidoka.Turn.State
• Jidoka.Turn.Transition
• Jidoka.Turn.Cursor
• Jidoka.Turn.Result
• Jidoka.Effect.Intent
• Jidoka.Effect.Result
• Jidoka.Effect.Journal
• Jidoka.Effect.OperationRequest
• Jidoka.Effect.OperationResult
• Jidoka.Effect.LLMDecision
• Jidoka.Runtime.Capabilities

Related Guides

• Agent Spec Contract - the input to the plan.
• Operation Source Contracts - where operation capabilities come from.
• Runtime And Harness - the executor of these contracts.
• Import And Snapshot Contracts - durable shapes built on top of Turn.State and Turn.Cursor.