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 runners, traces, and storage layers can interoperate with the runtime without guessing.

When To Use This

• Use this guide when you are building a custom runner, 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 Execution Layers 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.Turn

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, _ctx ->
  {:ok, %{type: :final, content: "Chicago time is 09:30."}}
end

{:ok, result} = Jidoka.turn(MyApp.TimeAgent, 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 runtime only 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, an ordered content-part list, a map, or a keyword list. A content-part list keeps its full typed form in content. The request derives input from its text parts. If there is no text, it uses a non-empty summary such as "[Multimodal input: image, audio]". Input controls, memory, and dynamic instructions continue to receive a stable string.

Jidoka.ContentPart

Provider-neutral content for requests, messages, decisions, and results.

A media part must have exactly one source: url, data, or file_id. Use the builders to make this rule explicit:

alias Jidoka.ContentPart

input = [
  ContentPart.text("Describe this image."),
  ContentPart.image({:data, image_bytes},
    media_type: "image/png",
    filename: "diagram.png"
  ),
  ContentPart.audio({:file_id, "file_123"}, media_type: "audio/mpeg")
]

{:ok, result} = Jidoka.turn(MyApp.MediaAgent, input)

The ReqLLM adapter sends supported parts as native ReqLLM content parts. Image and video URLs stay as URLs. Inline media and file ids stay typed. ReqLLM does not have a provider-neutral native form for audio or document URLs. The adapter returns {:unsupported_media_source, type, :url} for those two cases. A provider can still reject a valid native part when its selected model does not support that media type. Jidoka returns that provider error without changing it.

Raw media is durable data. Signed snapshots preserve it so resume is lossless. Jidoka.project/1, debug prompt views, and terminal event data omit media bytes, URLs, and file ids. They show the type, source kind, media type, filename, byte size, and redacted metadata.

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.

A custom LLM capability can return typed output beside its final text:

{:ok,
 %{
   type: :final,
   content: "Created the image.",
   parts: [
     Jidoka.ContentPart.text("Created the image."),
     Jidoka.ContentPart.image({:data, image_bytes}, media_type: "image/png")
   ]
 }}

The built-in ReqLLM capability converts provider image, video, audio, and file parts into this contract. It also keeps provider metadata, response model, finish reason, message metadata, and usage on the LLM decision and its journal result.

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, LLMDecision.operation/3, and LLMDecision.operations/2 are the 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 either one final answer, one operation intent, or one ordered operation batch. Each resulting intent is recorded and observed once.
• 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, _ctx ->
    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} = Jidoka.turn(MyApp.TimeAgent, "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.ContentPart
• 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 Execution Layers - the executor of these contracts.
• Import And Snapshot Contracts - durable shapes built on top of Turn.State and Turn.Cursor.