Glossary

This guide is an alphabetical reference for the vocabulary used across the Jidoka docs, source, and tests. Each entry gives a short definition, the module that owns the contract, and the guide that explains the concept in context. Use it as a lookup when a term appears in another guide and you want a one-line anchor before reading further.

When To Use This

Use this guide when a term in another Jidoka guide or doctring needs a precise definition.
Use this guide as a starting point for navigating module-level docs: every row links to the canonical module.
Do not use this guide as a tutorial. The terms here assume you have already read Getting Started.

Prerequisites

A working install of :jidoka and the ability to open module docs with h Jidoka.<Module> in IEx.
Familiarity with Getting Started so the term shapes (spec, plan, harness, turn) are not new.

Concepts

Three concept buckets organize every term in this guide:

Authoring: how an agent is defined. Examples: Agent, DSL, Import, Instructions, Spec, Tool.
Data contracts: immutable values that flow through the runtime. Examples: Plan, Turn.Request, Turn.Result, Effect.Intent, Snapshot, Event.
Execution: process- or capability-side machinery that interprets data. Examples: Harness, Runtime, Capability, AgentServer, Memory.Store.

The diagram below shows how the most central terms relate inside a single turn.

╭───────────╮   ╭────────────╮   ╭──────────╮   ╭────────────╮
│ DSL/Import│──▶│ Agent.Spec │──▶│ Turn.Plan│──▶│  Harness   │
╰───────────╯   ╰────────────╯   ╰──────────╯   ╰─────┬──────╯
                                                      │
                            ╭─────────────────────────┴──────────────────────╮
                            ▼                                                ▼
                      ╭───────────╮                                    ╭──────────╮
                      │ Capability│ ⇄ Effect.Intent / Effect.Result ⇄  │ Journal  │
                      ╰───────────╯                                    ╰──────────╯
                            │
                            ▼
                      ╭────────────╮            ╭──────────────╮
                      │ Turn.Result│   or       │  Snapshot    │
                      ╰────────────╯            ╰──────────────╯

How To Read An Entry

Each row in the table follows the same shape:

Term: the canonical name as it appears in source, tests, and docs.
Definition: one paragraph; precise rather than friendly.
Module: the implementation home. Backtick-link to open the module doc.
Guide: the guide that introduces the term in context (when one exists).

Aliases are spelled out where they are common. For example, Spec is shorthand for Jidoka.Agent.Spec; the row lives under Agent.Spec with Spec listed as an alias.

Glossary

Term	Definition	Module	Guide
Action	Jidoka's thin wrapper over `Jido.Action`. An action is the canonical implementation of a tool: a module with a name, description, parameter schema, and `run/2` callback. Actions are turned into operations at compile time.	`Jidoka.Action`	Agent DSL
Agent	The author-facing concept of a Jidoka agent: a Spark DSL module that compiles to an immutable spec. An agent is not a process; it is a definition that can be planned, run, hosted, or imported.	`Jidoka.Agent`	Agent DSL
Agent.Spec	Immutable definition data for one agent (id, model, instructions, generation, controls, operations, context schema, result schema, memory policy, metadata). DSL modules and JSON/YAML imports both compile to this struct. Alias: `Spec`.	`Jidoka.Agent.Spec`	Agent DSL
AgentServer	The Jido process that hosts a Jidoka agent. Turns sent to a process arrive as `jidoka.turn.run` signals and are dispatched into the same harness as direct calls.	`Jido.AgentServer`	Runtime And Harness
AgentSnapshot	Serializable semantic snapshot used for hibernate/resume. Contains the schema version, snapshot id, agent id, cursor, and turn state. Snapshots are pure data and safe to persist. Alias: `Snapshot`.	`Jidoka.Runtime.AgentSnapshot`	Runtime And Harness
AgentView	Surface-neutral UI projection of an agent's status, last result, pending interrupts, and event tail. Used by LiveView, CLI, channels, and tests; never holds a pid or provider client.	`Jidoka.AgentView`	Runtime And Harness
Capability	A runtime function injected into the harness for a single turn. The bundle currently has two slots: `llm` and `operations`. Capabilities are what make turns either deterministic (fakes) or live (ReqLLM, Jido actions).	`Jidoka.Runtime.Capabilities`	Runtime And Harness
Checkpoint	The named phase boundary at which the runtime is allowed to hibernate. Configured per turn through the `checkpoint:` option; possible phases include `:after_prompt`, `:before_effect`, `:review`, and `:wait`.	`Jidoka.Turn.Cursor`	Runtime And Harness
Context	Caller-supplied per-turn map merged into the turn request. Validated against the spec's `context_schema` before the workflow runs. Context is data only; it never contains processes or clients.	`Jidoka.Turn.Request`	Agent DSL
Control	A policy module attached to a spec at one of three boundaries: input, operation, or output. Controls return `:allow`, `{:block, reason}`, or `{:interrupt, reason}` and run in the runtime shell.	`Jidoka.Control`	Controls
DSL	The Spark-based authoring surface used by `use Jidoka.Agent`. Provides the `agent`, `controls`, and `tools` sections plus compile-time verifiers.	`Jidoka.Agent`	Agent DSL
Effect	The umbrella name for anything the runtime has to ask the outside world to do (currently `:llm` and `:operation`). Effects are described by intents and observed through results.	`Jidoka.Effect.Intent`	Runtime And Harness
Effect.Intent	The durable data description of one external effect (kind, payload, idempotency key). Intents are written to the journal before any capability is called.	`Jidoka.Effect.Intent`	Runtime And Harness
Effect.Journal	Intent/result map that makes the loop replayable. The interpreter records an intent before calling a capability and short-circuits any intent that already has a recorded result.	`Jidoka.Effect.Journal`	Runtime And Harness
Effect.Result	Normalized result of an interpreted effect (status, output, metadata). One result is written per intent id.	`Jidoka.Effect.Result`	Runtime And Harness
Eval	A small deterministic eval runner that packages an agent, request, and assertions. It runs through `Jidoka.Harness` rather than introducing a parallel runtime.	`Jidoka.Eval`	Runtime And Harness
Event	Neutral harness data emitted by turn transitions (turn started, prompt assembled, effect started, control allowed, approval requested, etc.). Events feed traces, streams, and `AgentView`.	`Jidoka.Event`	Runtime And Harness
Generation	Provider-neutral generation parameters on a spec (temperature, max_tokens, top_p, etc.). Defaults come from `Jidoka.Config.default_generation/0`.	`Jidoka.Agent.Spec.Generation`	Agent DSL
Handoff	Durable routing data that records which agent should own future turns for a conversation. Different from a subagent call, which delegates one bounded task inside a turn.	`Jidoka.Handoff`	Runtime And Harness
Harness	The named execution boundary around the Jidoka kernel. Owns `run_turn/3`, `resume/2`, request normalization, capability normalization, memory wiring, and session/store integration.	`Jidoka.Harness`	Runtime And Harness
Hibernate	The act of pausing a turn at a checkpoint and emitting an `AgentSnapshot` instead of a `Turn.Result`. Used for human review pauses and externally driven resumes.	`Jidoka.Runtime.AgentSnapshot`	Runtime And Harness
Idempotency	Per-operation policy that tells the runtime how to treat repeated effects. Valid values: `:pure`, `:idempotent`, `:dedupe`, `:reconcile`, `:unsafe_once`. `:unsafe_once` requires a matching operation control.	`Jidoka.Agent.Spec.Operation`	Controls
Import	The runtime that parses JSON/YAML into an `Agent.Spec`. Imports never call `String.to_atom/1` on input; module and schema refs are resolved through caller-provided registries.	`Jidoka.Import`	Agent DSL
Inspection	Internal module that powers `Jidoka.inspect/1` and `Jidoka.preflight/3`. Returns stable, human-readable projections of agents, plans, turns, and snapshots.	`Jidoka.Inspection`	Getting Started
Instructions	The system-prompt-shaped string attached to a spec. Skills and memory contributions can extend instructions at runtime; the stored value is still data.	`Jidoka.Agent.Spec`	Agent DSL
Jido	The underlying process/agent framework that owns supervision, registries, signals, and action runtime. Jidoka treats Jido as a hosting and tool runtime; it does not embed Jido logic in the turn spine.	`Jido`	Runtime And Harness
Jidoka	The package itself: a data-first agent harness that compiles authored agents to a `Spec`, plans them into a `Turn.Plan`, and runs them through a thin harness.	`Jidoka`	Getting Started
LLM	The language-model capability slot. The runtime treats the model as an effect; an LLM capability is a 2-arity function over `(intent, journal)` returning a typed decision.	`Jidoka.Runtime.Capabilities`	Live LLM Tool Loop
LLMDecision	Typed decision returned by an LLM effect. Either `:final` (with content and optional structured result) or `:operation` (with name and arguments).	`Jidoka.Effect.LLMDecision`	Live LLM Tool Loop
MCP	Operation source for tools exposed by a Model Context Protocol server. Compiles MCP tool descriptors into `Agent.Spec.Operation` data plus an operation capability that invokes the MCP transport.	`Jidoka.Operation.Source`	Agent DSL
Memory	Visible agent memory: entries recalled into prompts or context, optionally captured from completed turns. The spec stores policy; runtime stores live behind the `Memory.Store` behaviour.	`Jidoka.Memory`	Runtime And Harness
Memory.Store	Behaviour for pluggable memory backends. A store implements `recall/2`, `write/2`, and `list_entries/1`. The store is supplied per run, not baked into the spec.	`Jidoka.Memory.Store`	Runtime And Harness
Operation	A model-callable unit (name, description, idempotency, metadata, optional parameters schema). Operations are how tools, MCP, browser, workflows, and subagents reach the model in a single shape.	`Jidoka.Agent.Spec.Operation`	Agent DSL
Operation.Source	Behaviour and compiler that normalize executable surfaces (actions, MCP, browser, workflows) into operation data plus one operation capability.	`Jidoka.Operation.Source`	Agent DSL
Output	A control boundary that runs against the model's final assistant content before it leaves the harness. Used for safety filters, redaction, and post-validation.	`Jidoka.Agent.Spec.Controls.Output`	Controls
Plan	Shorthand for `Turn.Plan`. The compiled, executable contract derived from a spec.	`Jidoka.Turn.Plan`	Runtime And Harness
Preflight	`Jidoka.preflight/3`. Assembles the prompt, tool metadata, memory contributions, and request normalization without calling an LLM. The cheapest way to validate wiring.	`Jidoka.Inspection`	Getting Started
Projection	Stable inspection map produced by `Jidoka.project/1`. Projections omit Zoi schemas, LLMDB structs, and Spark metadata while keeping the semantic shape useful for traces, golden tests, and UI rendering.	`Jidoka.Projection`	Runtime And Harness
Request	Shorthand for `Turn.Request`. Input for one agent turn: input string, request id, agent state, context, and metadata.	`Jidoka.Turn.Request`	Getting Started
Result	Shorthand for `Turn.Result`. The value `turn/3` returns on success: content, optional structured `value`, agent state, journal, and events.	`Jidoka.Turn.Result`	Structured Results
Resume	The act of continuing from an `AgentSnapshot`. The same harness runs as a fresh turn; callers supply the same capabilities plus any required approval response.	`Jidoka.Harness`	Runtime And Harness
ReqLLM	The third-party provider client used to make live model calls. Jidoka wraps ReqLLM behind a small adapter that emits typed `LLMDecision` values.	`Jidoka.Runtime.ReqLLM`	Live LLM Tool Loop
Review	The collection of structs and runtime helpers that model human-in-the-loop pauses (`Review.Request`, `Review.Response`, `Review.Interrupt`).	`Jidoka.Review`	Controls
Runic	The pure workflow engine that owns the turn spine. Jidoka compiles its phases into a Runic workflow so transitions stay deterministic and inspectable.	`Runic.Workflow`	Runtime And Harness
Runtime	The shell modules under `Jidoka.Runtime.*` that implement capabilities, controls, signals, and the turn runner. Effectful by design, kept around the pure core.	`Jidoka.Runtime.TurnRunner`	Runtime And Harness
Session	The ergonomic facade for durable multi-turn state. Delegates to `Jidoka.Harness.Session` for the underlying data shape.	`Jidoka.Session`	Runtime And Harness
Skill	A Jido.AI skill referenced by an agent. Skills contribute prompt instructions and any actions published by the skill manifest; those actions are executed through the standard Jido action operation path.	`Jidoka.Skill`	Agent DSL
Snapshot	See `AgentSnapshot`.	`Jidoka.Runtime.AgentSnapshot`	Runtime And Harness
Source	See `Operation.Source`.	`Jidoka.Operation.Source`	Agent DSL
Spark	The DSL framework used to build the Jidoka agent DSL. Provides sections, entities, verifiers, formatter support, and source-aware errors.	`Spark.Dsl.Extension`	Agent DSL
Spec	See `Agent.Spec`.	`Jidoka.Agent.Spec`	Agent DSL
Store	See `Memory.Store` or `Jidoka.Harness.Store` depending on context: harness stores persist sessions and snapshots, memory stores persist memory entries.	`Jidoka.Harness.Store`	Runtime And Harness
Stream	Request-scoped helper for observing `Jidoka.Event` values as a turn runs. Callers opt in with `stream_to: pid` or `on_event: fun`.	`Jidoka.Stream`	Runtime And Harness
Subagent	A bounded delegation to another agent for one task inside the current turn. Different from a handoff, which permanently changes conversation ownership.	`Jidoka.Agent.Spec.Operation`	Agent DSL
Tool	The author-facing name for a model-callable capability. In Jidoka, tools are normally `Jidoka.Action` modules and compile to `Operation` data.	`Jidoka.Action`	Agent DSL
Trace	Projection helpers that turn events into a compact, sequence-stable timeline. Useful for debugging and golden tests.	`Jidoka.Trace`	Runtime And Harness
Turn	One model/tool cycle: assemble prompt, plan model effect, apply model result, plan operation effects, apply operation results. The harness runs one turn per `turn/3` call.	`Jidoka.Turn.Plan`	Getting Started
Turn.Plan	The executable plan compiled from a spec. Holds the spec, workflow profile, `max_model_turns`, timeout, and phase list. Still pure data.	`Jidoka.Turn.Plan`	Runtime And Harness
Turn.Result	The final app-facing result of one turn: content, optional structured `value`, agent state, journal, and events.	`Jidoka.Turn.Result`	Structured Results
Turn.State	The ephemeral, in-flight data value the workflow threads through each phase. Hibernation snapshots the state at a checkpoint; resume rebuilds the runner from that snapshot.	`Jidoka.Turn.State`	Runtime And Harness
Unsafe Once	Idempotency level for operations whose effects must not be replayed. Spec validation requires a matching operation control before such an operation can ship in a plan.	`Jidoka.Agent.Spec.Operation`	Controls
Workflow	An application-owned deterministic process exposed to an agent as a single model-callable operation. Different from the Runic turn spine: the agent chooses when to call it, the workflow module owns the ordered process inside `run/2`.	`Jidoka.Workflow`	Agent DSL

Common Patterns

Look up before you read. When another guide uses a term you have not seen, find the row here first; the linked module doc is usually one line of context away.
Prefer canonical names. Use Agent.Spec instead of Spec in code comments and PR descriptions so search across the codebase stays reliable.
Keep aliases stable. Snapshot, Spec, Plan, Request, and Result are the common short forms; everything else should use the full name.

Troubleshooting

Symptom	Likely Cause	Fix
A term in a doctring is not in this table.	The term is application-level vocabulary, not Jidoka vocabulary.	Confirm by searching `lib/jidoka` for the term. If it is internal Jidoka vocabulary, add a row here.
A linked module raises `function not found`.	The module was renamed or moved.	Run `mix compile` and search `lib/` for the new home, then update the row.
Two guides use the term differently.	One guide is stale.	Pick the meaning that matches the current module doc and open an issue against the stale guide.