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

A2UI protocol-version registry and catalog compatibility rules.

Wire envelopes carry a string `version` field (`"v0.9"`, `"v0.9.1"`,
`"v1.0"`). This module holds the supported set and the exact
catalog-compatibility rule from the reference implementation
(`DEFAULT_CATALOG_COMPATIBILITY` + the "same major ≥ 1" SemVer rule
+ normalization for non-semver identifiers).

## Compatibility rule (verbatim from upstream)

1. Normalize both sides via `A2UICore.SemVer.to_canonical/1`.
2. Equal canonicals ⇒ compatible.
3. The explicit map (below) extends compatibility per message version.
4. If both sides are SemVer and the catalog's major is ≥ 1 and equals
   the message's major, they're compatible (minor/patch ignored).
5. Otherwise — fallback: normalized raw string equality.

# `protocol_version`
*since 0.1.0* 

```elixir
@type protocol_version() :: String.t()
```

# `all`
*since 0.1.0* 

```elixir
@spec all() :: [protocol_version()]
```

All protocol versions known to this library, including legacy ones.

# `catalog_compatible?`
*since 0.1.0* 

```elixir
@spec catalog_compatible?(term(), term()) :: boolean()
```

Whether `catalog_version` is compatible with `message_version`
per the rule documented in the moduledoc.

## Examples

    iex> A2UICore.Version.catalog_compatible?("v1.0", "v1.0")
    true
    iex> A2UICore.Version.catalog_compatible?("v0.9", "v0.9.1")
    true
    iex> A2UICore.Version.catalog_compatible?("v0.9.1", "v0.9")
    true
    iex> A2UICore.Version.catalog_compatible?("v1.0", "v0.9")
    false
    iex> A2UICore.Version.catalog_compatible?("unknown", "v1.0")
    false

# `catalog_compatible?`
*since 0.1.0* 

```elixir
@spec catalog_compatible?(term(), term(), map()) :: boolean()
```

# `default_catalog_compatibility`
*since 0.1.0* 

```elixir
@spec default_catalog_compatibility() :: %{
  required(String.t()) => MapSet.t(String.t())
}
```

The default catalog-compatibility map (normalized canonical keys).

Message canonical version → the catalog canonical versions it accepts.

# `protocol_version?`
*since 0.1.0* 

```elixir
@spec protocol_version?(term()) :: boolean()
```

True if `version` (after SemVer parse) matches a known protocol version.
The candidate may be written `0.9`, `v0.9`, `0.9.1`, `v0.9.1`, `v1.0`.

# `supported`
*since 0.1.0* 

```elixir
@spec supported() :: [protocol_version()]
```

The versions this build implements. v0.8 is intentionally excluded.

# `to_protocol_version`
*since 0.1.0* 

```elixir
@spec to_protocol_version(term()) :: {:ok, protocol_version()} | :error
```

Resolves the protocol version a version designator names.

`v0.9`, `v0.9.1` and `v1.0` (and any SemVer-equal variant such as
`1.0.0-beta`) round-trip to the same protocol version. Invalid strings
produce `:error` (never raise).

---

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