# ADR-033 Migration Notes (v0.11.0)

This guide covers the v0.11.0 breaking contract changes for plugin metadata
and resolver behavior.

## What changed

1. `plugin_meta['plugin_api_version']` is now validated as semver-like:
   `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`.
2. `plugin_meta['data_modalities']` is now normalized/validated:
   canonical modalities plus `x-<vendor>-<name>` extensions.
3. Modality-aware explanation resolver now raises explicit ambiguity errors
   when multiple top-priority candidates match.

## Defaults for legacy plugins

If missing, CE now applies:

- `plugin_api_version = "1.0"`
- `data_modalities = ("tabular",)`

## Before and after

Before (accepted legacy metadata):

```python
plugin_meta = {
    "schema_version": 1,
    "name": "my.plugin",
    "version": "0.1",
    "provider": "acme",
    "capabilities": ("explain",),
}
```

After (explicit and future-proof):

```python
plugin_meta = {
    "schema_version": 1,
    "name": "my.plugin",
    "version": "0.1",
    "provider": "acme",
    "capabilities": ("explain",),
    "plugin_api_version": "1.0",
    "data_modalities": ("tabular",),
}
```

## Modality taxonomy

Canonical modalities:

- `tabular`
- `vision`
- `audio`
- `text`
- `multimodal`

Alias normalization examples:

- `image` -> `vision`
- `img` -> `vision`

Custom modalities must use `x-` namespace, e.g. `x-acme-graph`.

## Resolver ambiguity break

v0.11.0 now fails explicitly when modality resolution has multiple
top-priority matches. To migrate:

1. Set explicit plugin `priority` metadata to break ties, or
2. Provide an explicit plugin identifier override where resolution is invoked.