feat: Implement middleware priority for ordered execution, including range validation and adapter updates.

Author: tercel

CHANGELOG.md

@@ -5,6 +5,12 @@ 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.13.3] - 2026-03-24
+
+### Added
+- **Middleware priority** — `Middleware` base class now accepts `priority: int` (0-1000, default 0). Higher priority executes first; equal priority preserves registration order. `BeforeMiddleware` and `AfterMiddleware` adapters also accept `priority`.
+- **Priority range validation** — `ValueError` raised for priority values outside 0-1000
+
 ## [0.13.2] - 2026-03-22
 
 ### Changed

pyproject.toml

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

src/apcore/middleware/adapters.py

@@ -12,8 +12,11 @@
 class BeforeMiddleware(Middleware):
     """Wraps a before-only callback function as a Middleware instance."""
 
-    def __init__(self, callback: Callable[[str, dict[str, Any], Context], dict[str, Any] | None]) -> None:
+    def __init__(
+        self, callback: Callable[[str, dict[str, Any], Context], dict[str, Any] | None], *, priority: int = 0
+    ) -> None:
         """Store the callback for delegation."""
+        super().__init__(priority=priority)
         self._callback = callback
 
     def before(self, module_id: str, inputs: dict[str, Any], context: Context) -> dict[str, Any] | None:
@@ -27,8 +30,11 @@ class AfterMiddleware(Middleware):
     def __init__(
         self,
         callback: Callable[[str, dict[str, Any], dict[str, Any], Context], dict[str, Any] | None],
+        *,
+        priority: int = 0,
     ) -> None:
         """Store the callback for delegation."""
+        super().__init__(priority=priority)
         self._callback = callback
 
     def after(

src/apcore/middleware/base.py

@@ -12,8 +12,20 @@ class Middleware:
 
     Subclass and override the methods you need. All methods return None by
     default, which signals 'no modification' to the middleware pipeline.
+
+    Attributes:
+        priority: Execution priority (0-1000). Higher priority executes first.
+            Middlewares with equal priority preserve registration order.
+            Defaults to 0 for backward compatibility.
     """
 
+    priority: int = 0
+
+    def __init__(self, *, priority: int = 0) -> None:
+        if not (0 <= priority <= 1000):
+            raise ValueError(f"priority must be between 0 and 1000, got {priority}")
+        self.priority = priority
+
     def before(self, module_id: str, inputs: dict[str, Any], context: Context) -> dict[str, Any] | None:
         """Called before module execution. Return modified inputs or None."""
         return None

src/apcore/middleware/manager.py

@@ -44,9 +44,21 @@ def __init__(self) -> None:
         self._lock = threading.Lock()
 
     def add(self, middleware: Middleware) -> None:
-        """Append a middleware to the end of the execution list."""
+        """Insert a middleware sorted by priority (higher first).
+
+        Middlewares with equal priority preserve registration order
+        (stable insertion). Priority range is 0-1000 per the protocol spec.
+        """
         with self._lock:
-            self._middlewares.append(middleware)
+            # Find the first position where the existing middleware has a
+            # lower priority. This keeps higher-priority items first and
+            # preserves registration order among equal priorities.
+            insert_idx = len(self._middlewares)
+            for i, existing in enumerate(self._middlewares):
+                if existing.priority < middleware.priority:
+                    insert_idx = i
+                    break
+            self._middlewares.insert(insert_idx, middleware)
 
     def remove(self, middleware: Middleware) -> bool:
         """Remove a middleware by identity (is). Returns True if found and removed."""

tests/test_middleware.py

@@ -1,4 +1,4 @@
-"""Tests for the Middleware base class and function adapters."""
+"""Tests for the Middleware base class, function adapters, and priority ordering."""
 
 from __future__ import annotations
 
@@ -8,6 +8,7 @@
 
 from apcore.context import Context
 from apcore.middleware import AfterMiddleware, BeforeMiddleware, Middleware
+from apcore.middleware.manager import MiddlewareManager
 
 
 # === Middleware Base Class ===
@@ -169,3 +170,129 @@ def test_callback_receives_correct_args(self) -> None:
         ctx = MagicMock(spec=Context)
         am.after("mod.id", {"k": "v"}, {"out": 1}, ctx)
         spy.assert_called_once_with("mod.id", {"k": "v"}, {"out": 1}, ctx)
+
+
+# === Middleware Priority Ordering ===
+
+
+class TestMiddlewarePriority:
+    """Tests for middleware priority ordering in MiddlewareManager."""
+
+    def test_default_priority_is_zero(self) -> None:
+        """Middleware instances default to priority 0."""
+        mw = Middleware()
+        assert mw.priority == 0
+
+    def test_custom_priority(self) -> None:
+        """Middleware accepts a custom priority via constructor."""
+        mw = Middleware(priority=500)
+        assert mw.priority == 500
+
+    def test_higher_priority_executes_first(self) -> None:
+        """Middlewares with higher priority appear earlier in the list."""
+        manager = MiddlewareManager()
+        low = Middleware(priority=100)
+        high = Middleware(priority=900)
+        mid = Middleware(priority=500)
+
+        manager.add(low)
+        manager.add(high)
+        manager.add(mid)
+
+        snapshot = manager.snapshot()
+        assert snapshot == [high, mid, low]
+
+    def test_equal_priority_preserves_registration_order(self) -> None:
+        """Middlewares with the same priority are ordered by registration time."""
+        manager = MiddlewareManager()
+        first = Middleware(priority=100)
+        second = Middleware(priority=100)
+        third = Middleware(priority=100)
+
+        manager.add(first)
+        manager.add(second)
+        manager.add(third)
+
+        snapshot = manager.snapshot()
+        assert snapshot == [first, second, third]
+
+    def test_mixed_priorities_with_ties(self) -> None:
+        """Mixed priorities sort correctly with registration-order tiebreaking."""
+        manager = MiddlewareManager()
+        a = Middleware(priority=500)
+        b = Middleware(priority=100)
+        c = Middleware(priority=500)
+        d = Middleware(priority=1000)
+        e = Middleware(priority=0)
+
+        manager.add(a)
+        manager.add(b)
+        manager.add(c)
+        manager.add(d)
+        manager.add(e)
+
+        snapshot = manager.snapshot()
+        assert snapshot == [d, a, c, b, e]
+
+    def test_default_priority_backward_compatible(self) -> None:
+        """Middlewares without explicit priority still work (default 0)."""
+        manager = MiddlewareManager()
+        mw1 = Middleware()
+        mw2 = Middleware()
+        mw3 = Middleware()
+
+        manager.add(mw1)
+        manager.add(mw2)
+        manager.add(mw3)
+
+        snapshot = manager.snapshot()
+        assert snapshot == [mw1, mw2, mw3]
+
+    def test_subclass_without_super_init_defaults_to_zero(self) -> None:
+        """Subclasses that don't call super().__init__() still have priority 0."""
+
+        class CustomMiddleware(Middleware):
+            def __init__(self) -> None:
+                self.custom_field = "hello"
+
+        mw = CustomMiddleware()
+        assert mw.priority == 0
+
+    def test_remove_preserves_priority_order(self) -> None:
+        """Removing a middleware preserves the priority-sorted order."""
+        manager = MiddlewareManager()
+        low = Middleware(priority=100)
+        high = Middleware(priority=900)
+        mid = Middleware(priority=500)
+
+        manager.add(low)
+        manager.add(high)
+        manager.add(mid)
+        manager.remove(mid)
+
+        snapshot = manager.snapshot()
+        assert snapshot == [high, low]
+
+    def test_priority_below_zero_raises_value_error(self) -> None:
+        """Priority below 0 raises ValueError."""
+        import pytest
+
+        with pytest.raises(ValueError, match="priority must be between 0 and 1000"):
+            Middleware(priority=-1)
+
+    def test_priority_above_1000_raises_value_error(self) -> None:
+        """Priority above 1000 raises ValueError."""
+        import pytest
+
+        with pytest.raises(ValueError, match="priority must be between 0 and 1000"):
+            Middleware(priority=1001)
+
+    def test_before_middleware_accepts_priority(self) -> None:
+        """BeforeMiddleware forwards priority to the base class."""
+        bm = BeforeMiddleware(lambda mid, inp, ctx: None, priority=42)
+        assert bm.priority == 42
+
+    def test_after_middleware_accepts_priority(self) -> None:
+        """AfterMiddleware forwards priority to the base class."""
+        am = AfterMiddleware(lambda mid, inp, out, ctx: None, priority=99)
+        assert am.priority == 99