Release v0.1.9

Documentation

New: Plugin Contract

Added plugins/contract.md — single source of
truth for plugin authors. Covers:

• stability labels (stable / provisional / internal) for every
  entry-point group
• what each label promises through the 0.1.x → 0.2.x transition
• plugin author obligations (base class requirements, internal path
  restrictions)
• what the runtime does with incompatible plugins (excluded from active
  registry, still in diagnostics)
• stable base class shapes for sources, sinks, middlewares, dedup stores,
  and dedup strategies

New: Manifest Contract

Added plugins/manifest.md — explains the
two-version model that plugin authors frequently confuse:

• AGORA_PLUGIN_MANIFEST_VERSION = "0.3" tracks the MANIFEST metadata
  schema, not the agora-etl package version
• full compatibility matrix (matching / mismatching / no MANIFEST)
• how to read the registry_entrypoint_incompatible warning
• deprecation notice for AGORA_API_VERSION alias (removed in 0.2.0)
• when AGORA_PLUGIN_MANIFEST_VERSION bumps vs when the package bumps

Updated: plugins/index.md and plugins/developing.md

• plugins/index.md now links to contract.md and manifest.md from the
  "Start here" section.
• plugins/developing.md "Manifest compatibility" section now points to
  manifest.md instead of carrying its own short paragraph.

MkDocs nav

Added Plugin Contract and Manifest Contract to the Plugins section in
mkdocs.yml.

Code

Deprecation: AGORA_API_VERSION

Added a deprecation docstring to AGORA_API_VERSION in
agora/core/registry.py. The alias still works and resolves to the same
value as AGORA_PLUGIN_MANIFEST_VERSION. It will be removed in 0.2.0.

Migration is a one-line change:

# Before
from agora.core.registry import AGORA_API_VERSION

# After
from agora.core.registry import AGORA_PLUGIN_MANIFEST_VERSION

Clearer incompatibility warning

The registry_entrypoint_incompatible log message now includes a hint
field that tells operators exactly what to update and where to find the
compatibility model. Behavior is unchanged — only the message is more
actionable.

Tests

Preservation: plugin contract

Added tests/preservation/test_plugin_contract.py (19 tests):

• AGORA_API_VERSION alias equals AGORA_PLUGIN_MANIFEST_VERSION
• each stable entry-point group has a Registry at the declared module
  path and attribute, with load_entrypoints() callable (6 groups)
• each provisional entry-point group has a Registry at the declared
  path (4 groups)
• manifest matrix: matching version → loaded, compatible=True
• manifest matrix: mismatching version → excluded, compatible=False,
  still in diagnostics
• manifest matrix: no MANIFEST → loaded, compatible=None
• incompatible plugin does not abort discovery of other plugins in the
  same group
• built-in sources registered under their declared names
• built-in sinks registered under their declared names
• built-in runners registered under their declared names
• describe_items() returns RegistryItemInfo objects

All 72 preservation tests pass (53 from 0.1.8 + 19 new).