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

Canonical pod topology data structure.

Topologies are pure data. They define the named durable nodes that a pod
manages and can be validated, stored, and mutated independently of runtime
process state.

# `node_name`

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

# `t`

```elixir
@type t() :: %Jido.Pod.Topology{
  defaults: map(),
  links: [
    %Jido.Pod.Topology.Link{
      from: atom() | binary(),
      meta: map(),
      to: atom() | binary(),
      type: atom()
    }
  ],
  name: binary(),
  nodes: map(),
  version: integer()
}
```

# `delete_link`

```elixir
@spec delete_link(t(), Jido.Pod.Topology.Link.t() | tuple() | keyword() | map()) ::
  t()
```

Removes a link from the topology.

# `delete_node`

```elixir
@spec delete_node(t(), node_name()) :: t()
```

Removes a node from the topology.

# `dependencies_of`

```elixir
@spec dependencies_of(t(), node_name()) :: [node_name()]
```

Returns the direct `:depends_on` prerequisites for the given node.

# `dependency_order`

```elixir
@spec dependency_order(t(), [node_name()]) :: {:ok, [node_name()]} | {:error, term()}
```

Orders the given node names according to `:depends_on` links.

Only dependencies between the provided node names participate in ordering.
Other links are ignored.

# `fetch_node`

```elixir
@spec fetch_node(t(), node_name()) :: {:ok, Jido.Pod.Topology.Node.t()} | :error
```

Fetches a node by name.

# `from_nodes`

```elixir
@spec from_nodes(String.t(), map(), keyword()) :: {:ok, t()} | {:error, term()}
```

Builds a topology from the common shorthand node map form.

# `from_nodes!`

```elixir
@spec from_nodes!(String.t(), map(), keyword()) :: t()
```

Builds a topology from shorthand, raising on error.

# `new`

```elixir
@spec new(keyword() | map() | t()) :: {:ok, t()} | {:error, term()}
```

Builds a validated topology.

# `new!`

```elixir
@spec new!(keyword() | map() | t()) :: t()
```

Builds a validated topology, raising on error.

# `owned_children`

```elixir
@spec owned_children(t(), node_name()) :: [node_name()]
```

Returns the owned children for the given node.

# `owner_of`

```elixir
@spec owner_of(t(), node_name()) :: {:ok, node_name()} | :root | :error
```

Returns the logical owner of a node when the topology contains an `:owns` link.

# `put_link`

```elixir
@spec put_link(t(), Jido.Pod.Topology.Link.t() | tuple() | keyword() | map()) ::
  {:ok, t()} | {:error, term()}
```

Appends a link to the topology if it is not already present.

# `put_node`

```elixir
@spec put_node(t(), node_name(), Jido.Pod.Topology.Node.t() | keyword() | map()) ::
  {:ok, t()} | {:error, term()}
```

Inserts or replaces a node definition in the topology.

# `reconcile_waves`

```elixir
@spec reconcile_waves(t(), [node_name()]) :: {:ok, [[node_name()]]} | {:error, term()}
```

Builds runtime reconcile waves for the requested nodes.

Each wave contains nodes whose ownership and dependency prerequisites are
satisfied by earlier waves. The requested nodes are automatically expanded to
include transitive owners and dependencies.

# `roots`

```elixir
@spec roots(t()) :: [node_name()]
```

Returns the root nodes that have no logical `:owns` parent.

# `with_name`

```elixir
@spec with_name(t(), String.t()) :: {:ok, t()} | {:error, term()}
```

Returns a copy of the topology with a new validated name.