# `Jido.Pod`
[🔗](https://github.com/agentjido/jido/blob/v2.3.3/lib/jido/pod.ex#L1)

Pod wrapper macro and runtime helpers.

A pod is just a `Jido.Agent` with a canonical topology and a singleton pod
plugin mounted under the reserved `:__pod__` state key.

# `ensure_result`

```elixir
@type ensure_result() :: %{
  pid: pid(),
  source: ensure_source(),
  owner: node_name() | nil,
  parent: :pod | node_name()
}
```

# `ensure_source`

```elixir
@type ensure_source() :: :adopted | :running | :started
```

# `mutation_report`

```elixir
@type mutation_report() :: Jido.Pod.Mutation.Report.t()
```

# `node_name`

```elixir
@type node_name() :: Jido.Pod.Topology.node_name()
```

# `node_snapshot`

```elixir
@type node_snapshot() :: %{
  node: Jido.Pod.Topology.Node.t(),
  key: term(),
  pid: pid() | nil,
  running_pid: pid() | nil,
  adopted_pid: pid() | nil,
  owner: node_name() | nil,
  expected_parent: map(),
  actual_parent: map() | nil,
  adopted?: boolean(),
  status: node_status()
}
```

# `node_status`

```elixir
@type node_status() :: :adopted | :running | :misplaced | :stopped
```

# `reconcile_report`

```elixir
@type reconcile_report() :: %{
  requested: [node_name()],
  waves: [[node_name()]],
  nodes: %{required(node_name()) => ensure_result()},
  failures: %{required(node_name()) => term()},
  completed: [node_name()],
  failed: [node_name()],
  pending: [node_name()]
}
```

# `ensure_node`

```elixir
@spec ensure_node(Jido.AgentServer.server(), node_name(), keyword()) ::
  {:ok, pid()} | {:error, term()}
```

Ensures a named node is running and adopted into the pod manager.

# `fetch_state`

```elixir
@spec fetch_state(Jido.Agent.t() | Jido.AgentServer.State.t()) ::
  {:ok, map()} | {:error, term()}
```

Fetches pod plugin state from an agent or server state.

# `fetch_topology`

```elixir
@spec fetch_topology(
  module()
  | Jido.Agent.t()
  | Jido.AgentServer.State.t()
  | Jido.AgentServer.server()
) ::
  {:ok, Jido.Pod.Topology.t()} | {:error, term()}
```

Fetches the canonical topology from a module, agent, or running pod server.

# `get`

```elixir
@spec get(atom(), term(), keyword()) :: {:ok, pid()} | {:error, term()}
```

Gets a pod instance through the given `InstanceManager` and immediately
reconciles eager nodes.

This is the default happy path for pod lifecycle access. Call
`Jido.Agent.InstanceManager.get/3` directly if you need lower-level control
over reconciliation timing.

# `lookup_node`

```elixir
@spec lookup_node(Jido.AgentServer.server(), node_name()) ::
  {:ok, pid()} | :error | {:error, term()}
```

Looks up a node's live process if it is currently running.

# `mutate`

```elixir
@spec mutate(Jido.AgentServer.server(), [Jido.Pod.Mutation.t() | term()], keyword()) ::
  {:ok, mutation_report()} | {:error, mutation_report() | term()}
```

Applies live topology mutations to a running pod and waits for runtime work to finish.

`server` follows the same resolution rules as `Jido.AgentServer.state/1` and
`Jido.AgentServer.call/3`. Pass the running pod pid, a locally registered
server name, or another resolvable runtime server reference. Raw string ids
still require explicit registry lookup before use.

# `mutation_effects`

```elixir
@spec mutation_effects(Jido.Agent.t(), [Jido.Pod.Mutation.t() | term()], keyword()) ::
  {:ok, [struct()]} | {:error, term()}
```

Builds state ops and runtime effects for an in-turn pod mutation.

# `nodes`

```elixir
@spec nodes(Jido.AgentServer.server()) ::
  {:ok, %{required(node_name()) => node_snapshot()}} | {:error, term()}
```

Returns runtime snapshots for every node in a running pod.

# `pod_plugin_instance`

```elixir
@spec pod_plugin_instance(module()) ::
  {:ok, Jido.Plugin.Instance.t()} | {:error, term()}
```

Returns the reserved pod plugin instance for a pod-wrapped agent module.

# `put_topology`

```elixir
@spec put_topology(Jido.Agent.t(), Jido.Pod.Topology.t()) ::
  {:ok, Jido.Agent.t()} | {:error, term()}
```

Replaces the persisted topology snapshot in a pod agent.

Structural topology changes advance `topology.version`; no-op replacements
preserve the current version.

# `reconcile`

```elixir
@spec reconcile(
  Jido.AgentServer.server(),
  keyword()
) :: {:ok, reconcile_report()} | {:error, reconcile_report()}
```

Ensures all eager nodes are running and adopted into the pod manager.

# `update_topology`

```elixir
@spec update_topology(
  Jido.Agent.t(),
  (Jido.Pod.Topology.t() ->
     Jido.Pod.Topology.t() | {:ok, Jido.Pod.Topology.t()} | {:error, term()})
) :: {:ok, Jido.Agent.t()} | {:error, term()}
```

Applies a pure topology transformation to a pod agent.

Structural topology changes advance `topology.version`; no-op updates preserve
the current version.