# `A2UICore.Message.Adapter`
[🔗](https://github.com/a2ui-elixir/a2ui/blob/v0.1.1/umbrella/apps/a2ui_core/lib/a2ui_core/message/adapter.ex#L1)

Version adapter behaviour and the shared envelope-extraction pipeline.

Each protocol version implements the `c:Adapter` behaviour; the shared
`extract/3` pipeline (a faithful port of the reference
`BaseVersionAdapter.extract_operations`) drives them:

1. recursion/pointer preflight (`A2UICore.Validation.Integrity`),
2. payload unwrapping — `nil`/`[]` are no-ops, lists recurse per item
   (pre-checking the single-action rule for every item first), and
   `{"messages": [...]}` wrappers recurse into the list,
3. per-message checks, in this order:
   exactly one action key (with the reference's two distinct error
   messages), action payload must be an object, `surfaceId` must be a
   string when present, `version` presence and compatibility,
4. schema validation against the version's vendored envelope
   document — the message-type `$defs` entry selected by the action
   key (mirroring the reference's discriminated dispatch) with the
   active catalog bound to the `catalog.json` placeholder,
5. operation construction via `c:extract_operations/2`.

# `opts`
*since 0.1.0* 

```elixir
@type opts() :: keyword()
```

Adapter options: `:catalog` binds the catalog schema the envelope's
`catalog.json` references resolve against — a catalog schema map, or
`:permissive` for a stand-in that accepts any component object, theme
and well-formed function call (the processor checks components against
the catalog each surface actually uses).

# `compatible_catalog_versions`
*since 0.1.0* 

```elixir
@callback compatible_catalog_versions() :: MapSet.t(String.t())
```

# `document_version`
*since 0.1.0* 

```elixir
@callback document_version() :: String.t()
```

# `extract_operations`
*since 0.1.0* 

```elixir
@callback extract_operations(action :: String.t(), message :: map()) :: [
  A2UICore.Message.Operation.t()
]
```

# `prepare_message`
*since 0.1.0* 

```elixir
@callback prepare_message(map()) :: map()
```

# `valid_actions`
*since 0.1.0* 

```elixir
@callback valid_actions() :: [String.t()]
```

# `version`
*since 0.1.0* 

```elixir
@callback version() :: String.t()
```

# `__using__`
*since 0.1.0* *macro* 

The version adapter behaviour. All callbacks are pure.

# `extract`
*since 0.1.0* 

```elixir
@spec extract(module(), term(), opts()) ::
  {:ok, [A2UICore.Message.Operation.t()]} | {:error, A2UICore.Error.t()}
```

Extracts canonical operations from a raw payload using `adapter`.

Returns `{:ok, operations}` or `{:error, error}`.

---

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