release(0.18.0): annotations.extra precedence + remove legacy event aliases

Aligned with apcore v0.18.0 PROTOCOL_SPEC §4.4.1 wire format and §9.16
event naming convention. Two breaking surfaces:

1. ModuleAnnotations.from_dict precedence inversion (§4.4.1 rule 7)
   - When the same key appears both in nested 'extra' and as a top-level
     overflow key, the nested value now wins (was: overflow won)
   - Observable only in pathological inputs that mix both forms — no
     conformant producer emits this
   - Top-level overflow keys are still tolerated and merged into extra
     for backward compatibility

2. Legacy event aliases removed (§9.16 cleanup, deadline was v0.16)
   - No longer emit 'module_health_changed' alongside 'apcore.module.toggled'
   - No longer emit 'module_health_changed' alongside 'apcore.health.recovered'
   - No longer emit 'config_changed' alongside 'apcore.config.updated'
   - No longer emit 'config_changed' alongside 'apcore.module.reloaded'
   - Listeners must subscribe to canonical names only; see MIGRATION-v0.18.md

Other:
- Renamed private _emit_config_changed → _emit_module_reloaded for clarity
- Inline comment on legacy mode '0.16.0' baseline (intentional, not drift)
- Updated tests to assert single canonical event instead of dual emission
- README event mapping table dropped legacy column; added v0.18 warning

Test suite: 2239 passed, 2 xfailed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Signed-off-by: tercel <tercel.yi@gmail.com>

Author: tercel

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.18.0] - 2026-04-07
+
+### Removed (BREAKING)
+
+- **Legacy event aliases removed.** Per the §9.16 naming convention shipped in v0.15, the dual-emission transition period for `module_health_changed` and `config_changed` ended in this release (the original removal deadline was v0.16.0). Listeners that subscribed to these legacy names will no longer receive events. Migrate subscriptions to the canonical names:
+  - `module_health_changed` → `apcore.module.toggled` (from `system.control.toggle_feature`) **or** `apcore.health.recovered` (from `PlatformNotifyMiddleware`)
+  - `config_changed` → `apcore.config.updated` (from `system.control.update_config`) **or** `apcore.module.reloaded` (from `system.control.reload_module`)
+- **Renamed private method `_emit_config_changed` → `_emit_module_reloaded`** in `system.control.reload_module` to reflect the canonical event it emits. Private API, no public-surface impact.
+
+### Fixed
+
+- **`ModuleAnnotations.from_dict` precedence inversion** — Per PROTOCOL_SPEC §4.4.1 rule 7, when the same key appears both in a nested `extra` object and as a top-level overflow key, the **nested value now wins** (previously the top-level overflow would silently overwrite it). Behavior change is observable only in the pathological case where an input contains both forms of the same key — no conformant producer emits this. Top-level overflow keys are still tolerated and merged into `extra` for backward compatibility.
+
 ## [0.17.1] - 2026-04-06
 
 ### Added

README.md

@@ -170,14 +170,16 @@ The longest-prefix-match dispatch algorithm ensures that `APCORE_OBSERVABILITY_T
 
 Canonical event type names use dot-namespaced identifiers. `apcore.*` is reserved for core framework events; adapter packages use their own prefix (e.g., `apcore-mcp.*`).
 
-| Canonical name | Replaces | Emitted by |
-|---------------|---------|-----------|
-| `apcore.module.toggled` | `module_health_changed` | `system.control.toggle_feature` |
-| `apcore.health.recovered` | `module_health_changed` | `PlatformNotifyMiddleware` (error rate recovery) |
-| `apcore.config.updated` | `config_changed` | `system.control.update_config` |
-| `apcore.module.reloaded` | `config_changed` | `system.control.reload_module` |
-
-The legacy short-form names are still emitted alongside the canonical names during the transition period.
+| Canonical name | Emitted by |
+|---------------|-----------|
+| `apcore.module.toggled` | `system.control.toggle_feature` |
+| `apcore.health.recovered` | `PlatformNotifyMiddleware` (error rate recovery) |
+| `apcore.config.updated` | `system.control.update_config` |
+| `apcore.module.reloaded` | `system.control.reload_module` |
+
+> **v0.18.0 — legacy aliases removed.** Listeners that previously subscribed to
+> `module_health_changed` or `config_changed` will no longer receive events.
+> Migrate subscriptions to the canonical names above.
 
 ## Documentation
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apcore"
-version = "0.17.1"
+version = "0.18.0"
 description = "Schema-driven module standard for AI-perceivable interfaces"
 readme = "README.md"
 requires-python = ">=3.11"

src/apcore/config.py

@@ -95,6 +95,12 @@
 }
 
 #: Default configuration values.
+#:
+#: NOTE: ``version`` is the frozen baseline for legacy-mode configs (those
+#: that omit an explicit ``version`` field). It identifies the spec version
+#: whose semantics legacy mode parses against, NOT the current SDK version.
+#: Do not bump this with each spec MINOR — only when legacy-mode parsing
+#: semantics actually change.
 _DEFAULTS: dict[str, Any] = {
     "version": "0.16.0",
     "extensions": {

src/apcore/middleware/platform_notify.py

@@ -17,7 +17,7 @@ class PlatformNotifyMiddleware(Middleware):
 
     Emits ``error_threshold_exceeded`` when a module's error rate crosses the
     configured threshold, ``latency_threshold_exceeded`` when p99 latency
-    exceeds the limit, and ``module_health_changed`` when a previously alerted
+    exceeds the limit, and ``apcore.health.recovered`` when a previously alerted
     module recovers below ``threshold * 0.5``.
 
     Hysteresis prevents repeated alerts until recovery is observed.
@@ -169,31 +169,19 @@ def _check_latency_threshold(self, module_id: str) -> None:
                 self._alerted[module_id].add("latency")
 
     def _check_error_recovery(self, module_id: str) -> None:
-        """Emit apcore.health.recovered (canonical) and module_health_changed (legacy alias)."""
+        """Emit ``apcore.health.recovered`` (canonical event) when a previously alerted module recovers."""
         error_rate = self._compute_error_rate(module_id)
         with self._alert_lock:
             if "error_rate" not in self._alerted.get(module_id, set()):
                 return
             if error_rate < self._error_rate_threshold * 0.5:
-                timestamp = datetime.now(timezone.utc).isoformat()
-                data: dict[str, Any] = {"status": "recovered", "error_rate": error_rate}
                 self._emitter.emit(
                     ApCoreEvent(
                         event_type="apcore.health.recovered",
                         module_id=module_id,
-                        timestamp=timestamp,
-                        severity="info",
-                        data=data,
-                    )
-                )
-                # Legacy alias — remove in 0.16.0
-                self._emitter.emit(
-                    ApCoreEvent(
-                        event_type="module_health_changed",
-                        module_id=module_id,
-                        timestamp=timestamp,
+                        timestamp=datetime.now(timezone.utc).isoformat(),
                         severity="info",
-                        data=data,
+                        data={"status": "recovered", "error_rate": error_rate},
                     )
                 )
                 self._alerted[module_id].discard("error_rate")

src/apcore/module.py

@@ -106,13 +106,21 @@ def __post_init__(self) -> None:
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> ModuleAnnotations:
-        """Deserialize from dict, capturing unknown keys into extra."""
+        """Deserialize from dict per PROTOCOL_SPEC §4.4.1 wire format.
+
+        - The canonical form carries extension data under a nested ``extra`` object.
+        - Legacy top-level overflow keys (unknown keys at the annotations root) are
+          tolerated for backward compatibility and merged into ``extra``.
+        - When the same key appears in BOTH the nested ``extra`` AND as a top-level
+          overflow key, the nested value wins (§4.4.1 rule 7).
+        """
         known = {k: v for k, v in data.items() if k in _CANONICAL_FIELDS}
-        unknown = {k: v for k, v in data.items() if k not in _CANONICAL_FIELDS}
+        overflow = {k: v for k, v in data.items() if k not in _CANONICAL_FIELDS}
         explicit_extra = known.pop("extra", {})
         if not isinstance(explicit_extra, dict):
             explicit_extra = {}
-        extra: dict[str, Any] = {**explicit_extra, **unknown}
+        # §4.4.1 rule 7: nested explicit `extra` wins over legacy top-level overflow.
+        extra: dict[str, Any] = {**overflow, **explicit_extra}
         return cls(**known, extra=extra)
 
 

src/apcore/sys_modules/control.py

@@ -175,27 +175,18 @@ def _validate_post_set(self, key: str, value: Any, old_value: Any) -> bool:
         return True
 
     def _emit_event(self, key: str, old_value: Any, new_value: Any) -> None:
-        """Emit apcore.config.updated (canonical) and config_changed (legacy alias)."""
-        payload = ApCoreEvent(
-            event_type="apcore.config.updated",
-            module_id="system.control.update_config",
-            timestamp=datetime.now(timezone.utc).isoformat(),
-            severity="info",
-            data={
-                "key": key,
-                "old_value": old_value,
-                "new_value": new_value,
-            },
-        )
-        self._emitter.emit(payload)
-        # Legacy alias — remove in 0.16.0
+        """Emit ``apcore.config.updated`` (canonical event)."""
         self._emitter.emit(
             ApCoreEvent(
-                event_type="config_changed",
+                event_type="apcore.config.updated",
                 module_id="system.control.update_config",
-                timestamp=payload.timestamp,
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 severity="info",
-                data=payload.data,
+                data={
+                    "key": key,
+                    "old_value": old_value,
+                    "new_value": new_value,
+                },
             )
         )
 
@@ -290,7 +281,7 @@ def execute(self, inputs: dict[str, Any], context: Any) -> dict[str, Any]:
         elapsed_ms = (time.monotonic() - start) * 1000.0
 
         new_version = getattr(new_module, "version", "1.0.0")
-        self._emit_config_changed(module_id, previous_version, new_version)
+        self._emit_module_reloaded(module_id, previous_version, new_version)
         self._log_reload(module_id, previous_version, new_version, reason)
 
         return {
@@ -349,27 +340,18 @@ def _reregister_module(self, module_id: str, module: Any) -> None:
         """
         self._registry.register_internal(module_id, module)
 
-    def _emit_config_changed(self, module_id: str, previous_version: str, new_version: str) -> None:
-        """Emit apcore.module.reloaded (canonical) and config_changed (legacy alias)."""
-        payload = ApCoreEvent(
-            event_type="apcore.module.reloaded",
-            module_id=module_id,
-            timestamp=datetime.now(timezone.utc).isoformat(),
-            severity="info",
-            data={
-                "previous_version": previous_version,
-                "new_version": new_version,
-            },
-        )
-        self._emitter.emit(payload)
-        # Legacy alias — remove in 0.16.0
+    def _emit_module_reloaded(self, module_id: str, previous_version: str, new_version: str) -> None:
+        """Emit ``apcore.module.reloaded`` (canonical event)."""
         self._emitter.emit(
             ApCoreEvent(
-                event_type="config_changed",
+                event_type="apcore.module.reloaded",
                 module_id=module_id,
-                timestamp=payload.timestamp,
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 severity="info",
-                data=payload.data,
+                data={
+                    "previous_version": previous_version,
+                    "new_version": new_version,
+                },
             )
         )
 
@@ -491,23 +473,14 @@ def _apply_toggle(self, module_id: str, enabled: bool) -> None:
             self._toggle_state.disable(module_id)
 
     def _emit_event(self, module_id: str, enabled: bool) -> None:
-        """Emit apcore.module.toggled (canonical) and module_health_changed (legacy alias)."""
-        payload = ApCoreEvent(
-            event_type="apcore.module.toggled",
-            module_id=module_id,
-            timestamp=datetime.now(timezone.utc).isoformat(),
-            severity="info",
-            data={"enabled": enabled},
-        )
-        self._emitter.emit(payload)
-        # Legacy alias — remove in 0.16.0
+        """Emit ``apcore.module.toggled`` (canonical event)."""
         self._emitter.emit(
             ApCoreEvent(
-                event_type="module_health_changed",
+                event_type="apcore.module.toggled",
                 module_id=module_id,
-                timestamp=payload.timestamp,
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 severity="info",
-                data=payload.data,
+                data={"enabled": enabled},
             )
         )
 

tests/sys_modules/test_control.py

@@ -103,16 +103,14 @@ def test_update_config_emits_config_changed_event(self) -> None:
             {"key": "executor.default_timeout", "value": 5000, "reason": "event test"},
             None,
         )
-        # Two events: canonical (apcore.config.updated) + legacy alias (config_changed)
-        assert emitter.emit.call_count == 2
-        events = [call[0][0] for call in emitter.emit.call_args_list]
-        event_types = {e.event_type for e in events}
-        assert "apcore.config.updated" in event_types
-        assert "config_changed" in event_types
-        canonical = next(e for e in events if e.event_type == "apcore.config.updated")
-        assert canonical.data["key"] == "executor.default_timeout"
-        assert canonical.data["old_value"] == 30000
-        assert canonical.data["new_value"] == 5000
+        # Single canonical event (apcore.config.updated). Legacy 'config_changed'
+        # alias removed in v0.18.0 — see CHANGELOG and PROTOCOL_SPEC §9.16.
+        assert emitter.emit.call_count == 1
+        event = emitter.emit.call_args_list[0][0][0]
+        assert event.event_type == "apcore.config.updated"
+        assert event.data["key"] == "executor.default_timeout"
+        assert event.data["old_value"] == 30000
+        assert event.data["new_value"] == 5000
 
 
 class TestUpdateConfigRestrictedKeySysModulesEnabled:
@@ -386,15 +384,13 @@ def test_reload_module_emits_config_changed_event(self) -> None:
                 context=None,
             )
 
-        # Two events: canonical (apcore.module.reloaded) + legacy alias (config_changed)
-        assert mock_emit.call_count == 2
-        events = [call[0][0] for call in mock_emit.call_args_list]
-        assert all(isinstance(e, ApCoreEvent) for e in events)
-        event_types = {e.event_type for e in events}
-        assert "apcore.module.reloaded" in event_types
-        assert "config_changed" in event_types
-        canonical = next(e for e in events if e.event_type == "apcore.module.reloaded")
-        assert canonical.module_id == "my.module"
+        # Single canonical event (apcore.module.reloaded). Legacy 'config_changed'
+        # alias removed in v0.18.0 — see CHANGELOG and PROTOCOL_SPEC §9.16.
+        assert mock_emit.call_count == 1
+        event = mock_emit.call_args_list[0][0][0]
+        assert isinstance(event, ApCoreEvent)
+        assert event.event_type == "apcore.module.reloaded"
+        assert event.module_id == "my.module"
 
 
 class TestReloadModuleNoEventOnFailure:
@@ -616,9 +612,9 @@ def test_toggle_feature_module_not_found(self, _clear_disabled_modules: Any) ->
         assert exc_info.value.code == "MODULE_NOT_FOUND"
 
 
-class TestToggleFeatureEmitsModuleHealthChanged:
-    def test_toggle_feature_emits_module_health_changed(self, _clear_disabled_modules: Any) -> None:
-        """Verify emit() is called with canonical and legacy events on toggle."""
+class TestToggleFeatureEmitsCanonicalEvent:
+    def test_toggle_feature_emits_canonical_event(self, _clear_disabled_modules: Any) -> None:
+        """Verify emit() is called with the canonical apcore.module.toggled event on toggle."""
         registry, _ = _make_registry_with_module("my.module")
         emitter = EventEmitter()
         emitter.emit = MagicMock()  # type: ignore[method-assign]
@@ -627,16 +623,14 @@ def test_toggle_feature_emits_module_health_changed(self, _clear_disabled_module
             {"module_id": "my.module", "enabled": False, "reason": "test"},
             context=None,
         )
-        # Two events: canonical (apcore.module.toggled) + legacy alias (module_health_changed)
-        assert emitter.emit.call_count == 2
-        events = [call[0][0] for call in emitter.emit.call_args_list]
-        assert all(isinstance(e, ApCoreEvent) for e in events)
-        event_types = {e.event_type for e in events}
-        assert "apcore.module.toggled" in event_types
-        assert "module_health_changed" in event_types
-        canonical = next(e for e in events if e.event_type == "apcore.module.toggled")
-        assert canonical.module_id == "my.module"
-        assert canonical.data["enabled"] is False
+        # Single canonical event (apcore.module.toggled). Legacy
+        # 'module_health_changed' alias removed in v0.18.0.
+        assert emitter.emit.call_count == 1
+        event = emitter.emit.call_args_list[0][0][0]
+        assert isinstance(event, ApCoreEvent)
+        assert event.event_type == "apcore.module.toggled"
+        assert event.module_id == "my.module"
+        assert event.data["enabled"] is False
 
 
 class TestToggleFeatureSurvivesReload:

tests/test_annotations.py

@@ -119,6 +119,23 @@ def test_explicit_extra_merged_with_unknown(self) -> None:
         assert ann.extra["mcp.cat"] == "tools"
         assert ann.extra["new_field"] == "val"
 
+    def test_nested_extra_wins_over_top_level_collision(self) -> None:
+        # PROTOCOL_SPEC §4.4.1 rule 7: when the same key appears both nested and
+        # at the root, the nested value MUST win.
+        data = {
+            "mcp.category": "LEGACY_VALUE",
+            "extra": {"mcp.category": "CANONICAL_VALUE"},
+        }
+        ann = ModuleAnnotations.from_dict(data)
+        assert ann.extra["mcp.category"] == "CANONICAL_VALUE"
+
+    def test_legacy_flattened_form_still_accepted(self) -> None:
+        # Backward compatibility: top-level overflow keys still normalize into extra.
+        data = {"readonly": True, "mcp.category": "tools", "cli.approval_message": "ok?"}
+        ann = ModuleAnnotations.from_dict(data)
+        assert ann.readonly is True
+        assert ann.extra == {"mcp.category": "tools", "cli.approval_message": "ok?"}
+
     def test_missing_fields_use_defaults(self) -> None:
         ann = ModuleAnnotations.from_dict({})
         assert ann.readonly is False

tests/test_platform_notify_middleware.py

@@ -150,8 +150,9 @@ def test_after_emits_recovery_event(self) -> None:
 
         emitter.reset_mock()
         mw.after("mod.a", {}, {}, MagicMock())
-        # Should emit module_health_changed with status=recovered
-        recovery_calls = [c for c in emitter.emit.call_args_list if c[0][0].event_type == "module_health_changed"]
+        # Should emit apcore.health.recovered with status=recovered.
+        # Legacy 'module_health_changed' alias removed in v0.18.0.
+        recovery_calls = [c for c in emitter.emit.call_args_list if c[0][0].event_type == "apcore.health.recovered"]
         assert len(recovery_calls) == 1
         event: ApCoreEvent = recovery_calls[0][0][0]
         assert event.data["status"] == "recovered"