Change Log: 0.1.9

Released: May 28, 2026

Focus

Plugin contract stabilization. No new public APIs, no runtime behavior changes — 0.1.9 writes down which extension points are stable, separates manifest-schema versioning from package versioning, and adds preservation coverage so the plugin contract cannot drift silently.

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

Packaging

  • Bumped agora-etl to 0.1.9.