feat: implement Context redesign, Annotations extension, and ACL condition handlers

Context:
- Add ContextKey<T> typed accessor with get/set/delete/exists/scoped
- Define built-in context keys (_apcore.mw.* convention)
- Migrate middleware from raw string keys to typed ContextKey
- Add Context.serialize()/deserialize() with _context_version:1

Annotations:
- Add extra: dict extension field to ModuleAnnotations (frozen dataclass)
- Change pagination_style from Literal to str for extensibility
- Add DEFAULT_ANNOTATIONS constant and from_dict() classmethod
- Add __post_init__ for list→tuple coercion and extra copy

ACL:
- Add ACLConditionHandler protocol (sync + async)
- Add register_condition() class-level handler registry
- Extract identity_types/roles/max_call_depth into handler classes
- Add $or and $not compound condition operators
- Add async_check() method alongside sync check()
- Replace hardcoded if/else with handler dispatch (fail-closed)

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

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

Author: tercel

src/apcore/__init__.py

@@ -18,6 +18,15 @@
 )
 from apcore.cancel import CancelToken, ExecutionCancelledError
 from apcore.context import Context, ContextFactory, Identity
+from apcore.context_key import ContextKey
+from apcore.context_keys import (
+    LOGGING_START,
+    METRICS_STARTS,
+    REDACTED_OUTPUT,
+    RETRY_COUNT_BASE,
+    TRACING_SAMPLED,
+    TRACING_SPANS,
+)
 from apcore.registry import Registry
 from apcore.client import APCore
 from apcore.registry.registry import (
@@ -33,6 +42,7 @@
 
 # Module types
 from apcore.module import (
+    DEFAULT_ANNOTATIONS,
     Module,
     ModuleAnnotations,
     ModuleExample,
@@ -322,6 +332,13 @@ def enable(module_id: str, reason: str = "Enabled via APCore client") -> dict[st
     "ExecutionCancelledError",
     "Context",
     "ContextFactory",
+    "ContextKey",
+    "TRACING_SPANS",
+    "TRACING_SAMPLED",
+    "METRICS_STARTS",
+    "LOGGING_START",
+    "REDACTED_OUTPUT",
+    "RETRY_COUNT_BASE",
     "Identity",
     "Registry",
     "Executor",
@@ -350,6 +367,7 @@ def enable(module_id: str, reason: str = "Enabled via APCore client") -> dict[st
     "AutoApproveHandler",
     "CallbackApprovalHandler",
     # Module types
+    "DEFAULT_ANNOTATIONS",
     "Module",
     "ModuleAnnotations",
     "ModuleExample",

src/apcore/acl.py

@@ -6,21 +6,32 @@
 
 from __future__ import annotations
 
+import inspect
 import logging
 import os
 import threading
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Any, Callable
+from typing import Any, Callable, ClassVar
 
 import yaml
 
+from apcore.acl_handlers import (
+    ACLConditionHandler,
+    _IdentityTypesHandler,
+    _MaxCallDepthHandler,
+    _NotHandler,
+    _OrHandler,
+    _RolesHandler,
+)
 from apcore.context import Context
 from apcore.errors import ACLRuleError, ConfigNotFoundError
 from apcore.utils.pattern import match_pattern
 
 __all__ = ["ACLRule", "AuditEntry", "ACL"]
 
+_logger = logging.getLogger(__name__)
+
 
 @dataclass
 class ACLRule:
@@ -64,6 +75,59 @@ class ACL:
         remove_rule, reload) are safe to call concurrently.
     """
 
+    _condition_handlers: ClassVar[dict[str, ACLConditionHandler]] = {}
+
+    @classmethod
+    def register_condition(cls, key: str, handler: ACLConditionHandler) -> None:
+        """Register a condition handler. Replaces existing handler for same key."""
+        cls._condition_handlers[key] = handler
+
+    @classmethod
+    def _evaluate_conditions(
+        cls, conditions: dict[str, Any], context: Context,
+    ) -> bool:
+        """Evaluate all conditions with AND logic. Fail-closed on unknown."""
+        for key, value in conditions.items():
+            handler = cls._condition_handlers.get(key)
+            if handler is None:
+                _logger.warning("Unknown ACL condition %r — treated as unsatisfied", key)
+                return False
+            try:
+                result = handler.evaluate(value, context)
+            except Exception:
+                _logger.exception("Handler for condition %r raised — treated as unsatisfied", key)
+                return False
+            if inspect.isawaitable(result):
+                result.close()  # prevent "coroutine never awaited" warning
+                _logger.warning(
+                    "Async condition %r in sync context — treated as unsatisfied. Use async_check().", key,
+                )
+                return False
+            if not result:
+                return False
+        return True
+
+    @classmethod
+    async def _evaluate_conditions_async(
+        cls, conditions: dict[str, Any], context: Context,
+    ) -> bool:
+        """Async variant. Awaits async handlers, calls sync handlers directly."""
+        for key, value in conditions.items():
+            handler = cls._condition_handlers.get(key)
+            if handler is None:
+                _logger.warning("Unknown ACL condition %r — treated as unsatisfied", key)
+                return False
+            try:
+                result = handler.evaluate(value, context)
+                if inspect.isawaitable(result):
+                    result = await result
+            except Exception:
+                _logger.exception("Handler for condition %r raised — treated as unsatisfied", key)
+                return False
+            if not result:
+                return False
+        return True
+
     def __init__(
         self,
         rules: list[ACLRule],
@@ -224,6 +288,97 @@ def check(
             audit_logger(entry)
         return default_decision
 
+    async def async_check(
+        self,
+        caller_id: str | None,
+        target_id: str,
+        context: Context | None = None,
+    ) -> bool:
+        """Async ACL check. Supports both sync and async condition handlers.
+
+        Args:
+            caller_id: The calling module ID, or None for external calls.
+            target_id: The target module ID being called.
+            context: Optional execution context for conditional rules.
+
+        Returns:
+            True if the call is allowed, False if denied.
+        """
+        effective_caller = "@external" if caller_id is None else caller_id
+
+        with self._lock:
+            rules = list(self._rules)
+            default_effect = self._default_effect
+            audit_logger = self._audit_logger
+
+        for idx, rule in enumerate(rules):
+            if await self._matches_rule_async(rule, effective_caller, target_id, context):
+                decision = rule.effect == "allow"
+                self._logger.debug(
+                    "ACL async_check: caller=%s target=%s decision=%s rule=%s",
+                    caller_id,
+                    target_id,
+                    "allow" if decision else "deny",
+                    rule.description or "(no description)",
+                )
+                if audit_logger is not None:
+                    entry = self._build_audit_entry(
+                        caller_id=effective_caller,
+                        target_id=target_id,
+                        decision="allow" if decision else "deny",
+                        reason="rule_match",
+                        matched_rule=rule,
+                        matched_rule_index=idx,
+                        context=context,
+                    )
+                    audit_logger(entry)
+                return decision
+
+        default_decision = default_effect == "allow"
+        self._logger.debug(
+            "ACL async_check: caller=%s target=%s decision=%s rule=default",
+            caller_id,
+            target_id,
+            "allow" if default_decision else "deny",
+        )
+        if audit_logger is not None:
+            reason = "no_rules" if not rules else "default_effect"
+            entry = self._build_audit_entry(
+                caller_id=effective_caller,
+                target_id=target_id,
+                decision="allow" if default_decision else "deny",
+                reason=reason,
+                matched_rule=None,
+                matched_rule_index=None,
+                context=context,
+            )
+            audit_logger(entry)
+        return default_decision
+
+    async def _matches_rule_async(
+        self,
+        rule: ACLRule,
+        caller: str,
+        target: str,
+        context: Context | None,
+    ) -> bool:
+        """Async version of _matches_rule that awaits async condition handlers."""
+        caller_match = any(self._match_pattern(p, caller, context) for p in rule.callers)
+        if not caller_match:
+            return False
+
+        target_match = any(self._match_pattern(p, target, context) for p in rule.targets)
+        if not target_match:
+            return False
+
+        if rule.conditions is not None:
+            if context is None:
+                return False
+            if not await self._evaluate_conditions_async(rule.conditions, context):
+                return False
+
+        return True
+
     def _build_audit_entry(
         self,
         *,
@@ -309,22 +464,7 @@ def _check_conditions(self, conditions: dict[str, Any], context: Context | None)
         """
         if context is None:
             return False
-
-        if "identity_types" in conditions:
-            if context.identity is None or context.identity.type not in conditions["identity_types"]:
-                return False
-
-        if "roles" in conditions:
-            if context.identity is None:
-                return False
-            if not set(context.identity.roles) & set(conditions["roles"]):
-                return False
-
-        if "max_call_depth" in conditions:
-            if len(context.call_chain) > conditions["max_call_depth"]:
-                return False
-
-        return True
+        return self._evaluate_conditions(conditions, context)
 
     def add_rule(self, rule: ACLRule) -> None:
         """Add a rule at position 0 (highest priority).
@@ -366,3 +506,14 @@ def reload(self) -> None:
         with self._lock:
             self._rules = reloaded._rules
             self._default_effect = reloaded._default_effect
+
+
+# ---------------------------------------------------------------------------
+# Auto-register built-in handlers at module load time
+# ---------------------------------------------------------------------------
+
+ACL.register_condition("identity_types", _IdentityTypesHandler())
+ACL.register_condition("roles", _RolesHandler())
+ACL.register_condition("max_call_depth", _MaxCallDepthHandler())
+ACL.register_condition("$or", _OrHandler(ACL._evaluate_conditions))
+ACL.register_condition("$not", _NotHandler(ACL._evaluate_conditions))

src/apcore/acl_handlers.py

@@ -0,0 +1,104 @@
+"""Built-in ACL condition handlers and handler protocols.
+
+Defines the ACLConditionHandler protocol (sync and async variants),
+three basic handlers (identity_types, roles, max_call_depth), and
+two compound operators ($or, $not).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Protocol, Union, runtime_checkable
+
+from apcore.context import Context
+
+__all__ = [
+    "SyncACLConditionHandler",
+    "AsyncACLConditionHandler",
+    "ACLConditionHandler",
+]
+
+
+@runtime_checkable
+class SyncACLConditionHandler(Protocol):
+    """Sync condition handler protocol."""
+
+    def evaluate(self, value: Any, context: Context) -> bool: ...
+
+
+@runtime_checkable
+class AsyncACLConditionHandler(Protocol):
+    """Async condition handler protocol."""
+
+    async def evaluate(self, value: Any, context: Context) -> bool: ...
+
+
+ACLConditionHandler = Union[SyncACLConditionHandler, AsyncACLConditionHandler]
+
+# Type alias for the recursive evaluation function used by compound handlers.
+_EvalFn = Callable[[dict[str, Any], Context], bool]
+
+
+# ---------------------------------------------------------------------------
+# Basic handlers
+# ---------------------------------------------------------------------------
+
+
+class _IdentityTypesHandler:
+    """Check context.identity.type is in the allowed list."""
+
+    def evaluate(self, value: Any, context: Context) -> bool:
+        if not isinstance(value, list) or context.identity is None:
+            return False
+        return context.identity.type in value
+
+
+class _RolesHandler:
+    """Check at least one role overlaps between identity and required roles."""
+
+    def evaluate(self, value: Any, context: Context) -> bool:
+        if not isinstance(value, list) or context.identity is None:
+            return False
+        return bool(set(context.identity.roles) & set(value))
+
+
+class _MaxCallDepthHandler:
+    """Check call chain length does not exceed threshold."""
+
+    def evaluate(self, value: Any, context: Context) -> bool:
+        if not isinstance(value, int):
+            return False
+        return len(context.call_chain) <= value
+
+
+# ---------------------------------------------------------------------------
+# Compound handlers
+# ---------------------------------------------------------------------------
+
+
+class _OrHandler:
+    """$or: list of condition dicts. Returns True if ANY sub-set passes."""
+
+    def __init__(self, evaluate_fn: _EvalFn) -> None:
+        self._evaluate = evaluate_fn
+
+    def evaluate(self, value: Any, context: Context) -> bool:
+        if not isinstance(value, list):
+            return False
+        for sub in value:
+            if not isinstance(sub, dict):
+                continue
+            if self._evaluate(sub, context):
+                return True
+        return False
+
+
+class _NotHandler:
+    """$not: single condition dict. Returns True if the sub-set FAILS."""
+
+    def __init__(self, evaluate_fn: _EvalFn) -> None:
+        self._evaluate = evaluate_fn
+
+    def evaluate(self, value: Any, context: Context) -> bool:
+        if not isinstance(value, dict):
+            return False
+        return not self._evaluate(value, context)