fix(types): clear all 31 pre-existing pyright errors

CLAUDE.md requires zero pyright errors before commit. The 31 errors
that had accumulated on main are now resolved. Full src/apcore/ scan
goes from 31 errors → 0.

Real type bugs fixed:
- executor.py:_translate_abort approval branch was constructing
  ApprovalDeniedError(message=...) without the required `result`
  parameter — would TypeError at runtime if the pipeline ever aborted
  at the approval_gate step. Now constructs synthetic ApprovalResult
  per status. (Pipeline v2 raises typed errors directly so this branch
  is rarely reached in practice, but it was still a runtime bug.)
- executor.py:_validate_async error_dict assignment was unsafe
  (`e.to_dict() if hasattr(e, "to_dict")`); now uses callable check
  + isinstance(produced, dict) narrowing.
- sys_modules/registration.py was passing MetricsCollector | None
  into HealthSummaryModule and HealthModuleModule, both of which
  declare MetricsCollector (non-Optional). Would crash at startup
  if metrics_collector was None. Now defaults to a fresh empty
  MetricsCollector so health modules degrade gracefully.

API improvements:
- ContextKey.get gains @overload signatures so key.get(ctx, default=v)
  narrows the return type to T (was T | None). Cleans up six
  append-on-None warnings in observability/{context_logger,metrics,
  usage}.py with no call-site changes.
- decorator._has_context_param renamed to _context_param_name and
  collapsed to return str | None (was tuple[bool, str | None]). The
  has_context boolean was redundant; checking `is not None` is enough.

Pure pyright satisfaction:
- Optional dependency imports (aiohttp, opentelemetry.*, watchdog.*)
  marked with `# type: ignore[import-not-found]` since they live
  inside try/except ImportError blocks.
- pydantic.fields.PydanticUndefined → pydantic_core.PydanticUndefined
  (canonical export path; pydantic.fields is the private re-export).
- builtin_steps.py:redact_sensitive call sites now cast()
  schema_dict_fn() result to dict[str, Any] (Pydantic contract).
- executor.Executor.__init__ strategy_kwargs gets explicit
  dict[str, Any] annotation to break the dict() inference union.
- pipeline._validate_dependencies adds tuple[str, ...] annotations
  for the getattr-derived requires/provides locals.
- pipeline_config._import_step BaseStep factory call now has a
  targeted call-arg ignore.
- context.deserialize services=None has the same arg-type ignore as
  the field declaration.
- pipeline_config factory call has a localized call-arg ignore.

Tests: tests/test_decorator.py updated to track the
_has_context_param → _context_param_name rename.

Verification: black ✓ ruff ✓ pyright ✓ pytest 2252/2252 ✓.

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

Author: tercel

src/apcore/builtin_steps.py

@@ -15,7 +15,7 @@
 import inspect
 import logging
 import time
-from typing import Any
+from typing import Any, cast
 
 import pydantic
 
@@ -488,7 +488,7 @@ async def execute(self, ctx: PipelineContext) -> StepResult:
         if schema_dict_fn is not None and callable(schema_dict_fn):
             from apcore.utils.redaction import redact_sensitive
 
-            schema = schema_dict_fn()
+            schema = cast(dict[str, Any], schema_dict_fn())
             redacted = redact_sensitive(ctx.inputs, schema)
             if ctx.context is not None and hasattr(ctx.context, "redacted_inputs"):
                 ctx.context.redacted_inputs = redacted
@@ -646,7 +646,7 @@ async def execute(self, ctx: PipelineContext) -> StepResult:
             if schema_dict_fn is not None and callable(schema_dict_fn):
                 from apcore.utils.redaction import redact_sensitive
 
-                schema = schema_dict_fn()
+                schema = cast(dict[str, Any], schema_dict_fn())
                 redacted = redact_sensitive(ctx.output, schema)
                 ctx.context.data[REDACTED_OUTPUT.name] = redacted
 

src/apcore/context.py

@@ -136,7 +136,7 @@ def deserialize(cls, data: dict[str, Any]) -> Context:
             identity=identity,
             redacted_inputs=data.get("redacted_inputs"),
             data=dict(data.get("data", {})),
-            services=None,
+            services=None,  # type: ignore[arg-type]
             cancel_token=None,
         )
 

src/apcore/context_key.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Generic, Protocol, TypeVar
+from typing import Any, Generic, Protocol, TypeVar, overload
 
 T = TypeVar("T")
 
-_MISSING = object()
+_MISSING: Any = object()
 
 
 class _ContextLike(Protocol):
@@ -26,10 +26,20 @@ class ContextKey(Generic[T]):
 
     name: str
 
-    def get(self, ctx: _ContextLike, default: T | None = None) -> T | None:  # type: ignore[type-var]
-        """Return the value for this key, or *default* if absent."""
+    @overload
+    def get(self, ctx: _ContextLike) -> T | None: ...
+
+    @overload
+    def get(self, ctx: _ContextLike, default: T) -> T: ...
+
+    def get(self, ctx: _ContextLike, default: T | None = None) -> T | None:
+        """Return the value for this key, or *default* if absent.
+
+        Overloaded so that ``key.get(ctx)`` returns ``T | None`` while
+        ``key.get(ctx, default=value)`` narrows the return type to ``T``.
+        """
         value = ctx.data.get(self.name, _MISSING)
-        return default if value is _MISSING else value  # type: ignore[return-value]
+        return default if value is _MISSING else value
 
     def set(self, ctx: _ContextLike, value: T) -> None:
         """Store *value* under this key in context.data."""

src/apcore/decorator.py

@@ -131,24 +131,25 @@ def generate_output_model(func: Any) -> type[BaseModel]:
     return create_model("OutputModel", result=(return_type, ...))
 
 
-def _has_context_param(func: Any) -> tuple[bool, str | None]:
-    """Check if any parameter has type annotation that is the Context class.
+def _context_param_name(func: Any) -> str | None:
+    """Return the name of the parameter typed as ``Context``, or None.
 
-    Returns (True, param_name) if found, (False, None) otherwise.
-    Detection is type-based, not name-based.
+    Detection is type-based, not name-based. Returns the parameter name when
+    a single ``Context``-typed parameter is found; returns ``None`` when the
+    function has no Context parameter or its annotations cannot be resolved.
     """
     try:
         hints = typing.get_type_hints(func, include_extras=True)
     except NameError:
-        return (False, None)
+        return None
 
     for param_name, hint in hints.items():
         if param_name == "return":
             continue
         if hint is Context:
-            return (True, param_name)
+            return param_name
 
-    return (False, None)
+    return None
 
 
 def _normalize_result(result: Any) -> dict[str, Any]:
@@ -193,7 +194,7 @@ def __init__(
         self.input_schema = input_schema if input_schema is not None else generate_input_model(func, param_descs)
         self.output_schema = output_schema if output_schema is not None else generate_output_model(func)
 
-        has_context, context_param_name = _has_context_param(func)
+        context_param_name = _context_param_name(func)
 
         # Description priority chain
         if description is not None:
@@ -223,7 +224,7 @@ def __init__(
 
             async def _async_execute(inputs: dict[str, Any], context: Context) -> dict[str, Any]:
                 call_kwargs = dict(inputs)
-                if has_context:
+                if context_param_name is not None:
                     call_kwargs[context_param_name] = context
                 result = await func(**call_kwargs)
                 return _normalize_result(result)
@@ -233,7 +234,7 @@ async def _async_execute(inputs: dict[str, Any], context: Context) -> dict[str,
 
             def _sync_execute(inputs: dict[str, Any], context: Context) -> dict[str, Any]:
                 call_kwargs = dict(inputs)
-                if has_context:
+                if context_param_name is not None:
                     call_kwargs[context_param_name] = context
                 result = func(**call_kwargs)
                 return _normalize_result(result)

src/apcore/events/subscribers.py

@@ -7,7 +7,7 @@
 from dataclasses import asdict
 
 try:
-    import aiohttp
+    import aiohttp  # type: ignore[import-not-found]
 except ImportError:
     aiohttp = None  # type: ignore[assignment]
 

src/apcore/executor.py

@@ -143,15 +143,15 @@ def __init__(
                 self._middleware_manager.add(mw)
 
         # Resolve strategy (pass middleware_manager and executor for production parity)
-        strategy_kwargs = dict(
-            registry=registry,
-            config=config,
-            acl=acl,
-            approval_handler=approval_handler,
-            middlewares=middlewares,
-            middleware_manager=self._middleware_manager,
-            executor=self,
-        )
+        strategy_kwargs: dict[str, Any] = {
+            "registry": registry,
+            "config": config,
+            "acl": acl,
+            "approval_handler": approval_handler,
+            "middlewares": middlewares,
+            "middleware_manager": self._middleware_manager,
+            "executor": self,
+        }
         if strategy is None:
             from apcore.builtin_steps import build_standard_strategy
 
@@ -401,7 +401,12 @@ async def _validate_async(
         except Exception as e:
             # Step raised an error (e.g., ModuleNotFoundError, ACLDeniedError)
             # Convert to a failed check using the error's own code/dict
-            error_dict = e.to_dict() if hasattr(e, "to_dict") else {"code": type(e).__name__, "message": str(e)}
+            error_dict: dict[str, Any] = {"code": type(e).__name__, "message": str(e)}
+            to_dict_fn = getattr(e, "to_dict", None)
+            if callable(to_dict_fn):
+                produced = to_dict_fn()
+                if isinstance(produced, dict):
+                    error_dict = produced
             code = getattr(e, "code", type(e).__name__)
 
             # Determine which check failed based on error type
@@ -487,12 +492,15 @@ def _translate_abort(self, abort: PipelineAbortError) -> ModuleError:
                     caller_id, target_id = pair[0].strip(), pair[1].strip()
             return ACLDeniedError(caller_id=caller_id, target_id=target_id)
         if step == "approval_gate":
-            if "rejected" in explanation.lower() or "denied" in explanation.lower():
-                return ApprovalDeniedError(message=explanation)
-            if "timeout" in explanation.lower():
-                return ApprovalTimeoutError(message=explanation)
-            if "pending" in explanation.lower():
-                return ApprovalPendingError(message=explanation)
+            from apcore.approval import ApprovalResult
+
+            lowered = explanation.lower()
+            if "rejected" in lowered or "denied" in lowered:
+                return ApprovalDeniedError(result=ApprovalResult(status="rejected", reason=explanation))
+            if "timeout" in lowered:
+                return ApprovalTimeoutError(result=ApprovalResult(status="timeout", reason=explanation))
+            if "pending" in lowered:
+                return ApprovalPendingError(result=ApprovalResult(status="pending", reason=explanation))
         if step == "input_validation" and "validation failed" in explanation.lower():
             return SchemaValidationError(message=explanation)
         if step == "output_validation" and "validation failed" in explanation.lower():

src/apcore/observability/tracing.py

@@ -124,13 +124,13 @@ def __init__(
             ImportError: If required opentelemetry packages are not installed.
         """
         try:
-            from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import (  # type: ignore[import-not-found]
                 OTLPSpanExporter as _OTLPSpanExporter,
             )
-            from opentelemetry.sdk.resources import Resource
-            from opentelemetry.sdk.trace import TracerProvider
-            from opentelemetry.sdk.trace.export import SimpleSpanProcessor
-            from opentelemetry.trace import StatusCode
+            from opentelemetry.sdk.resources import Resource  # type: ignore[import-not-found]
+            from opentelemetry.sdk.trace import TracerProvider  # type: ignore[import-not-found]
+            from opentelemetry.sdk.trace.export import SimpleSpanProcessor  # type: ignore[import-not-found]
+            from opentelemetry.trace import StatusCode  # type: ignore[import-not-found]
         except ImportError:
             raise ImportError(
                 "opentelemetry packages are required for OTLPExporter. "

src/apcore/pipeline.py

@@ -153,15 +153,15 @@ def _validate_dependencies(self) -> None:
         """Warn if any step's requires are not provided by a preceding step."""
         provided: set[str] = set()
         for step in self.steps:
-            requires = getattr(step, "requires", ())
+            requires: tuple[str, ...] = getattr(step, "requires", ())
             missing = set(requires) - provided
             if missing:
                 _logger.warning(
                     "Step '%s' requires %s, but no preceding step provides them. " "This may cause runtime errors.",
                     step.name,
                     missing,
                 )
-            provides = getattr(step, "provides", ())
+            provides: tuple[str, ...] = getattr(step, "provides", ())
             provided.update(provides)
 
     def insert_after(self, anchor: str, step: Step) -> None:

src/apcore/pipeline_config.py

@@ -83,7 +83,9 @@ def _resolve_step(step_def: dict[str, Any]) -> BaseStep:
     if type_name and type_name in _step_type_registry:
         factory = _step_type_registry[type_name]
         if isinstance(factory, type) and issubclass(factory, BaseStep):
-            step = factory(**config) if config else factory()
+            # Factory is a BaseStep subclass; either it provides defaults for
+            # `name` (most user steps do) or the YAML supplied `config` overrides.
+            step = factory(**config) if config else factory()  # type: ignore[call-arg]
         else:
             step = factory(config)
         # Override metadata from YAML

src/apcore/registry/registry.py

@@ -932,8 +932,8 @@ def watch(self) -> None:
         Raises ImportError if watchdog is not installed.
         """
         try:
-            from watchdog.observers import Observer
-            from watchdog.events import FileSystemEventHandler, FileSystemEvent
+            from watchdog.observers import Observer  # type: ignore[import-not-found]
+            from watchdog.events import FileSystemEventHandler, FileSystemEvent  # type: ignore[import-not-found]
         except ImportError:
             raise ImportError("watchdog is required for hot reload. Install it with: pip install watchdog")