Jido.Runic.Introspection (Jido.Runic v1.0.0)

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.

Summary

Types

fact_source()

graph_edge()

graph_node()

node_info()

node_status()

provenance_entry()

Functions

annotated_graph(workflow, strat_state)

Return the workflow graph annotated with execution status per node.

execution_summary(workflow)

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

node_map(workflow)

Return a map of all registered components in a workflow.

provenance_chain(source, fact_hash)

Walk Fact ancestry back through the workflow's facts.

step_report(strat_state)

Produce a report from strategy state step history.

workflow_graph(workflow)

Return a structured graph representation of workflow nodes and edges.

Types

fact_source()

@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()

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

graph_node()

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

node_info()

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

node_status()

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

provenance_entry()

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

Functions

annotated_graph(workflow, strat_state)

@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(workflow)

@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(workflow)

@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(source, fact_hash)

@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(strat_state)

@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(workflow)

@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.