# `Jido.Runic.Introspection`
[🔗](https://github.com/agentjido/jido_runic/blob/v1.0.0/lib/jido/runic/introspection.ex#L1)

Provenance queries, workflow execution summaries, and graph introspection.

Provides utilities to trace how facts were produced through a workflow,
generate summary statistics about execution state, inspect strategy
step history, and produce structured graph representations for UI rendering.

# `fact_source`

```elixir
@type fact_source() ::
  %Runic.Workflow{
    after_hooks: term(),
    before_hooks: term(),
    build_log: term(),
    components: term(),
    emit_events: term(),
    graph: term(),
    hash: term(),
    input_ports: term(),
    inputs: term(),
    mapped: term(),
    name: term(),
    output_ports: term(),
    run_context: term(),
    runnable_events: term(),
    scheduler_policies: term(),
    uncommitted_events: term()
  }
  | %{facts: [Runic.Workflow.Fact.t()]}
```

# `graph_edge`

```elixir
@type graph_edge() :: %{from: integer(), to: integer(), label: atom()}
```

# `graph_node`

```elixir
@type graph_node() :: %{name: atom(), hash: integer(), type: atom()}
```

# `node_info`

```elixir
@type node_info() :: %{
  hash: integer(),
  inputs: keyword(),
  outputs: keyword(),
  type: atom(),
  action_mod: module() | nil
}
```

# `node_status`

```elixir
@type node_status() :: :pending | :completed | :failed | :waiting | :idle
```

# `provenance_entry`

```elixir
@type provenance_entry() :: {Runic.Workflow.Fact.t(), integer() | nil}
```

# `annotated_graph`

```elixir
@spec annotated_graph(Runic.Workflow.t(), map()) :: %{
  nodes: [map()],
  edges: [graph_edge()]
}
```

Return the workflow graph annotated with execution status per node.

Combines the static workflow graph with strategy state to annotate each node
with its current execution status:

  * `:completed` — node hash is in `ran_nodes`
  * `:pending` — node hash is in `pending` (currently executing)
  * `:failed` — strategy status is `:failure` and node was not completed
  * `:waiting` — strategy status is `:waiting`
  * `:idle` — no execution activity for this node

# `execution_summary`

```elixir
@spec execution_summary(Runic.Workflow.t()) :: %{
  total_nodes: non_neg_integer(),
  facts_produced: non_neg_integer(),
  satisfied: boolean(),
  productions: non_neg_integer()
}
```

Return a summary map with execution statistics for the given workflow.

Keys returned:

  * `:total_nodes` — count of registered components
  * `:facts_produced` — count of facts in the workflow
  * `:satisfied` — `true` when the workflow has no remaining runnables
  * `:productions` — count of raw production values

# `node_map`

```elixir
@spec node_map(Runic.Workflow.t()) :: %{required(atom()) => node_info()}
```

Return a map of all registered components in a workflow.

Returns `%{node_name => node_info}` where `node_info` includes `:hash`,
`:inputs`, `:outputs`, `:type`, and `:action_mod` (for `Jido.Runic.ActionNode`).

# `provenance_chain`

```elixir
@spec provenance_chain(fact_source(), Runic.Workflow.Fact.hash()) ::
  {:ok, [provenance_entry()]} | {:error, :fact_not_found}
```

Walk Fact ancestry back through the workflow's facts.

Returns a list of `{fact, producing_node_hash_or_nil}` tuples ordered
from the root input fact to the target fact identified by `fact_hash`.

Accepts either a `%Runic.Workflow{}` or a map with a `:facts` key.

Returns `{:ok, chain}` on success, or `{:error, :fact_not_found}` if the
target fact is not found.

# `step_report`

```elixir
@spec step_report(map()) :: [map()]
```

Produce a report from strategy state step history.

Takes a strategy state map (as returned by `StratState.get(agent)`) and
returns a list of step report maps with enriched info about each tracked node.

Each map contains:

  * `:hash` — the node hash
  * `:status` — `:completed` if in `ran_nodes`, `:pending` if in `pending`, `:queued` otherwise
  * `:pending_since` — runnable struct if currently pending, `nil` otherwise

# `workflow_graph`

```elixir
@spec workflow_graph(Runic.Workflow.t()) :: %{
  nodes: [graph_node()],
  edges: [graph_edge()]
}
```

Return a structured graph representation of workflow nodes and edges.

Returns `%{nodes: [...], edges: [...]}` where each node has `:name`, `:hash`,
`:type` and each edge has `:from`, `:to`, `:label`.

Only includes structural edges (excludes runtime fact edges like `:produced`,
`:ran`, etc.) to represent the static workflow topology.

---

*Consult [api-reference.md](api-reference.md) for complete listing*