feat: add minimal execution strategy and implement step dependency validation via requires/provides metadata

Author: tercel

CHANGELOG.md

@@ -5,6 +5,20 @@ 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.17.1] - 2026-04-06
+
+### Added
+
+- **`build_minimal_strategy()`** — 4-step pipeline (context → lookup → execute → return) for pre-validated internal hot paths. Registered as `"minimal"` in Executor preset builders.
+- **`requires` / `provides` on `BaseStep`** — Optional advisory fields declaring step dependencies. `ExecutionStrategy` validates dependency chains at construction and insertion, emitting warnings for unmet `requires`.
+
+### Fixed
+
+- **`"minimal"` added to preset builders** — `Executor(strategy="minimal")` now works. Previously missing from `_resolve_strategy_name()` preset dict.
+- **Executor docstrings updated** — Constructor and `_resolve_strategy_name` docstrings now list all 5 presets (was missing `"minimal"`).
+
+---
+
 ## [0.17.0] - 2026-04-05
 
 ### Added

src/apcore/builtin_steps.py

@@ -54,6 +54,7 @@
     "build_internal_strategy",
     "build_testing_strategy",
     "build_performance_strategy",
+    "build_minimal_strategy",
 ]
 
 _logger = logging.getLogger(__name__)
@@ -91,6 +92,7 @@ def __init__(
             removable=False,
             replaceable=False,
             pure=True,
+            provides=("context",),
         )
         self._config = config
         self._executor = executor
@@ -129,6 +131,7 @@ def __init__(self, *, config: Any | None = None) -> None:
             removable=True,
             replaceable=True,
             pure=True,
+            requires=("context",),
         )
         self._config = config
         if config is not None:
@@ -166,6 +169,7 @@ def __init__(self, *, registry: Any) -> None:
             removable=False,
             replaceable=False,
             pure=True,
+            provides=("module",),
         )
         self._registry = registry
 
@@ -196,6 +200,7 @@ def __init__(self, *, acl: Any | None = None) -> None:
             removable=True,
             replaceable=True,
             pure=True,
+            requires=("context", "module"),
         )
         self._acl = acl
 
@@ -236,6 +241,7 @@ def __init__(
             removable=True,
             replaceable=True,
             pure=False,
+            requires=("context", "module"),
         )
         self._handler = handler
         self._executor = executor
@@ -404,6 +410,8 @@ def __init__(self) -> None:
             removable=True,
             replaceable=True,
             pure=True,
+            requires=("module",),
+            provides=("validated_inputs",),
         )
 
     async def execute(self, ctx: PipelineContext) -> StepResult:
@@ -455,6 +463,8 @@ def __init__(self, *, config: Any | None = None) -> None:
             removable=False,
             replaceable=True,
             pure=False,
+            requires=("module",),
+            provides=("output",),
         )
         self._config = config
         if config is not None:
@@ -553,6 +563,8 @@ def __init__(self) -> None:
             removable=True,
             replaceable=True,
             pure=True,
+            requires=("module", "output"),
+            provides=("validated_output",),
         )
 
     async def execute(self, ctx: PipelineContext) -> StepResult:
@@ -665,6 +677,7 @@ def __init__(self) -> None:
             removable=False,
             replaceable=False,
             pure=True,
+            requires=("output",),
         )
 
     async def execute(self, ctx: PipelineContext) -> StepResult:
@@ -777,3 +790,28 @@ def build_performance_strategy(**kwargs: Any) -> ExecutionStrategy:
     s.remove("middleware_after")
     object.__setattr__(s, "name", "performance")
     return s
+
+
+def build_minimal_strategy(**kwargs: Any) -> ExecutionStrategy:
+    """Build a minimal strategy: context → lookup → execute → return only.
+
+    Suitable for pre-validated internal hot paths where ACL, approval,
+    middleware, and schema validation are unnecessary. Use with caution —
+    no safety checks, no input/output validation, no middleware.
+
+    Args:
+        **kwargs: Forwarded to build_standard_strategy().
+
+    Returns:
+        An ExecutionStrategy named "minimal" with 4 steps.
+    """
+    s = build_standard_strategy(**kwargs)
+    s.remove("call_chain_guard")
+    s.remove("acl_check")
+    s.remove("approval_gate")
+    s.remove("middleware_before")
+    s.remove("input_validation")
+    s.remove("output_validation")
+    s.remove("middleware_after")
+    object.__setattr__(s, "name", "minimal")
+    return s

src/apcore/executor.py

@@ -154,7 +154,8 @@ def __init__(
             registry: Module registry for looking up modules by ID.
             strategy: Optional execution strategy. Can be an ExecutionStrategy
                 instance, a preset name string ("standard", "internal",
-                "testing", "performance"), or None (defaults to standard).
+                "testing", "performance", "minimal"), or None (defaults to
+                standard).
             middlewares: Optional list of middleware instances to register.
             acl: Optional ACL for access control enforcement.
             config: Optional configuration for timeout/depth settings.
@@ -875,7 +876,7 @@ def _resolve_strategy_name(name: str, **kwargs: Any) -> ExecutionStrategy:
 
         Args:
             name: Strategy name ("standard", "internal", "testing", "performance",
-                or a previously registered name).
+                "minimal", or a previously registered name).
             **kwargs: Forwarded to preset builder functions.
 
         Returns:
@@ -886,6 +887,7 @@ def _resolve_strategy_name(name: str, **kwargs: Any) -> ExecutionStrategy:
         """
         from apcore.builtin_steps import (
             build_internal_strategy,
+            build_minimal_strategy,
             build_performance_strategy,
             build_standard_strategy,
             build_testing_strategy,
@@ -896,6 +898,7 @@ def _resolve_strategy_name(name: str, **kwargs: Any) -> ExecutionStrategy:
             "internal": build_internal_strategy,
             "testing": build_testing_strategy,
             "performance": build_performance_strategy,
+            "minimal": build_minimal_strategy,
         }
 
         if name in preset_builders:

src/apcore/pipeline.py

@@ -53,6 +53,8 @@ def __init__(
         ignore_errors: bool = False,
         pure: bool = False,
         timeout_ms: int = 0,
+        requires: tuple[str, ...] = (),
+        provides: tuple[str, ...] = (),
     ) -> None:
         self.name = name
         self.description = description
@@ -62,6 +64,8 @@ def __init__(
         self.ignore_errors = ignore_errors
         self.pure = pure
         self.timeout_ms = timeout_ms
+        self.requires = requires
+        self.provides = provides
 
     @abstractmethod
     async def execute(self, ctx: PipelineContext) -> StepResult: ...
@@ -143,6 +147,22 @@ def __init__(self, name: str, steps: list[Step]) -> None:
         if len(names) != len(set(names)):
             dupes = [n for n in names if names.count(n) > 1]
             raise StepNameDuplicateError(f"Duplicate step names: {set(dupes)}")
+        self._validate_dependencies()
+
+    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", ())
+            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", ())
+            provided.update(provides)
 
     def insert_after(self, anchor: str, step: Step) -> None:
         """Insert a step after the named anchor step."""
@@ -151,6 +171,7 @@ def insert_after(self, anchor: str, step: Step) -> None:
         for i, s in enumerate(self.steps):
             if s.name == anchor:
                 self.steps.insert(i + 1, step)
+                self._validate_dependencies()
                 return
         raise StepNotFoundError(f"Anchor step '{anchor}' not found")
 
@@ -161,6 +182,7 @@ def insert_before(self, anchor: str, step: Step) -> None:
         for i, s in enumerate(self.steps):
             if s.name == anchor:
                 self.steps.insert(i, step)
+                self._validate_dependencies()
                 return
         raise StepNotFoundError(f"Anchor step '{anchor}' not found")