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):

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

After (explicit and future-proof):

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.