# `Beaver.MLIR.CompilationPlan`

A reusable, inspectable, cache-stable MLIR compiler declaration.

A plan closes Composer-compatible pass data, a Transform schedule, target and
schema configuration, bytecode version, context options, and telemetry metadata
into one value. It owns no MLIR context or native resource.

Pipeline strings and nested pipeline strings are deterministic data. Module and
callback passes contain executable behavior, so each such step must be wrapped
with an explicit stable version through `add_pass/3` or `versioned/2`. Function
bodies, processes, references, and native handles are never hashed.

`declaration/1` projects the executable plan to deterministic data, while
`identity/1` hashes that projection. Both are computed from the current struct;
no cached identity can drift from a modified plan.

# `pass_step`

```elixir
@type pass_step() ::
  binary()
  | module()
  | {binary(), [pass_step()]}
  | {binary(), binary(), function()}
  | {:beaver_compilation_plan_versioned_step, term(), term()}
```

# `t`

```elixir
@type t() :: %Beaver.MLIR.CompilationPlan{
  context_options: keyword(),
  desired_emit_version: integer() | nil,
  pipeline: [pass_step()],
  schema_version: term(),
  target: term(),
  telemetry_metadata: map(),
  transform_options: keyword(),
  transform_schedule:
    Beaver.MLIR.Transform.Schedule.Resolved.t() | binary() | nil
}
```

# `add_pass`

```elixir
@spec add_pass(t(), term(), keyword()) :: t()
```

Appends one Composer-compatible pass, optionally with `:version`.

# `declaration`

```elixir
@spec declaration(t()) :: map()
```

Returns the deterministic, callback-free declaration represented by a plan.

# `defcompiler`
*macro* 

Defines a zero-arity function that returns a validated compilation plan.

# `identity`

```elixir
@spec identity(t()) :: binary()
```

Returns the stable SHA-256 identity of `declaration/1`.

# `nested`

```elixir
@spec nested(t(), binary(), [pass_step()]) :: t()
```

Appends a nested Composer pass scope.

# `new`

```elixir
@spec new(keyword()) :: t()
```

Creates and validates a compilation plan without constructing native resources.

# `set_bytecode_version`

```elixir
@spec set_bytecode_version(t(), integer() | :current | nil) :: t()
```

Sets the desired MLIR bytecode emission version.

# `set_context_options`

```elixir
@spec set_context_options(
  t(),
  keyword()
) :: t()
```

Sets options used when the compilation runtime creates an MLIR context.

# `set_schema_version`

```elixir
@spec set_schema_version(t(), term()) :: t()
```

Sets the dynamic dialect/schema identity.

# `set_target`

```elixir
@spec set_target(t(), term()) :: t()
```

Sets the target configuration included in the plan identity.

# `set_telemetry_metadata`

```elixir
@spec set_telemetry_metadata(t(), map() | keyword()) :: t()
```

Sets deterministic metadata attached to compilation and artifact telemetry.

# `set_transform_schedule`

```elixir
@spec set_transform_schedule(
  t(),
  Beaver.MLIR.Transform.Schedule.Resolved.t() | binary() | nil,
  keyword()
) :: t()
```

Sets the Transform schedule and its execution options.

# `validate!`

```elixir
@spec validate!(t()) :: t()
```

Validates a plan and returns it unchanged.

# `versioned`

```elixir
@spec versioned(term(), term()) :: pass_step()
```

Wraps one Composer pass payload with an explicit stable version.