docs: update core executor pipeline documentation and add RFC for declarative step metadata.

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

Author: tercel

CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.17.0] - 2026-04-04
+
+### Added
+
+#### Pipeline v2 — Declarative Step Metadata
+- **4 new BaseStep fields** — `match_modules` (glob patterns for selective step execution), `ignore_errors` (fault-tolerant continuation on step failure), `pure` (no side effects, safe for dry-run/validate mode), `timeout_ms` (per-step timeout in milliseconds). Implemented across all three SDKs (Python, TypeScript, Rust).
+- **`PipelineContext.dry_run`** — When `true`, PipelineEngine skips steps with `pure=false`, enabling `validate()` to run user-defined pure steps automatically.
+- **`PipelineContext.version_hint`** — Passed through to module_lookup for version negotiation.
+- **`PipelineContext.executed_middlewares`** — Tracks which middleware ran for on_error recovery chain.
+- **`StepTrace.skip_reason`** — Records why a step was skipped: `"no_match"`, `"dry_run"`, or `"error_ignored"`.
+- **YAML pipeline configuration** (Python) — `pipeline` section in `apcore.yaml` with `remove`, `configure`, and `steps` directives. Step resolution via `type` (registry) and `handler` (import path).
+
+### Changed
+
+#### Pipeline Step Rename
+- **`safety_check` → `call_chain_guard`** — Renamed across all SDKs to accurately describe the step's purpose (call chain depth/cycle/repeat checks, not transport-level rate limiting).
+- **TypeScript `builtin.` prefix removed** — All built-in step names in the TypeScript SDK dropped the `builtin.` prefix for cross-SDK consistency (e.g., `builtin.context_creation` → `context_creation`).
+
+#### Pipeline Step Order
+- **Steps 6 and 7 swapped** — `middleware_before` now executes before `input_validation` (was the reverse). Middleware transforms are now validated by the subsequent input_validation step, aligning with the Kubernetes Mutating → Validating admission order.
+
+### Fixed
+- **Middleware transforms now validated** — Previously, middleware modifications to inputs were either never re-validated (production code) or silently discarded (pipeline abstraction). The step order swap ensures transformed inputs pass schema validation.
+
+---
+
 ## [0.16.0] - 2026-04-05
 
 ### Added

docs/api/executor-api.md

@@ -613,7 +613,7 @@ executor.call(module_id, inputs, context)
     ├─ 1. Create/validate Context
     │      └─ If context is None, auto-create
     │
-    ├─ 2. Call chain safety checks
+    ├─ 2. Call chain guard
     │      ├─ 2a. Depth check: len(call_chain) >= 32 → throw CallDepthExceededError
     │      ├─ 2b. Cycle detection: module_id in call_chain → throw CircularCallError
     │      └─ 2c. Frequency detection: call_chain.count(module_id) >= max_repeat → throw CallFrequencyExceededError
@@ -633,13 +633,13 @@ executor.call(module_id, inputs, context)
     │      └─ If timeout, throw ApprovalTimeoutError
     │      └─ If pending, throw ApprovalPendingError (Phase B)
     │
-    ├─ 6. Input validation
-    │      └─ Validate against input_schema
-    │      └─ If failed, throw ValidationError
-    │
-    ├─ 7. Middleware before
+    ├─ 6. Middleware before
     │      └─ middleware.before(module_id, inputs, context)
     │
+    ├─ 7. Input validation
+    │      └─ Validate against input_schema (includes middleware transforms)
+    │      └─ If failed, throw ValidationError
+    │
     ├─ 8. Execute module
     │      └─ module.execute(inputs, context)
     │      └─ If failed, call middleware on_error
@@ -653,6 +653,9 @@ executor.call(module_id, inputs, context)
     └─ 11. Return result
 ```
 
+!!! info "BaseStep Declarative Fields"
+    Each step in the pipeline now supports four declarative metadata fields: `match_modules` (glob patterns for selective execution), `ignore_errors` (fault-tolerant continuation), `pure` (dry-run safety marker), and `timeout_ms` (per-step timeout). See [Core Executor](../features/core-executor.md) for details.
+
 ### 6.2 Automatic Context Handling
 
 When modules internally call other modules, Executor automatically handles Context:
@@ -682,7 +685,7 @@ result = context.executor.call(
        ▼
   ┌──────────┐  depth/cycle/freq  ┌──────────────────────────┐
   │call_chain│───────────────────▶│ error: DEPTH_EXCEEDED    │
-  │  guard   │                    │      / CIRCULAR_CALL     │
+  │  guard   │ (was safety_check) │      / CIRCULAR_CALL     │
   └────┬─────┘                    │      / FREQUENCY_EXCEEDED│
        │ check passed             └──────────────────────────┘
        ▼
@@ -703,18 +706,18 @@ result = context.executor.call(
        │                         └──────────────────────────┘
        │ approved (or skipped)
        ▼
+  ┌──────────┐
+  │ before   │──── middleware error ──▶ on_error chain
+  │middleware│
+  └────┬─────┘
+       │ transforms applied
+       ▼
   ┌──────────┐   validation failed ┌──────────────────────┐
   │ validate │────────────────────▶│ error: VALIDATION    │
   │  input   │                     └──────────────────────┘
   └────┬─────┘
        │ validation passed
        ▼
-  ┌──────────┐
-  │ before   │──── middleware error ──▶ on_error chain
-  │middleware│
-  └────┬─────┘
-       │
-       ▼
   ┌──────────┐   execution error  ┌──────────────────────┐
   │ execute  │────────────────────▶│ on_error middleware  │
   │  module  │                     └──────────────────────┘

docs/features/core-executor.md

@@ -22,7 +22,7 @@ The executor processes every module call through the following pipeline:
 
 1. **Context Creation** -- A `Context` object is constructed carrying the caller identity, call metadata, and any propagated state from parent calls. This context flows through every subsequent step.
 
-2. **Safety Checks** -- Three safety mechanisms are evaluated before proceeding:
+2. **Call Chain Guard** -- Three safety mechanisms are evaluated before proceeding:
    - *Call depth check*: Rejects calls that exceed the configured maximum nesting depth, preventing unbounded recursion.
    - *Circular call detection*: Inspects the call chain recorded in the context to detect and reject circular module invocations.
    - *Frequency throttling*: Tracks call frequency per module and rejects calls that exceed the configured rate, protecting against tight-loop abuse.
@@ -33,9 +33,9 @@ The executor processes every module call through the following pipeline:
 
 5. **Approval Gate** -- If an `ApprovalHandler` is configured and the module declares `requires_approval=true`, the handler is invoked to obtain approval before proceeding. The handler may block for human input or return immediately. Rejected, timed-out, or still-pending approvals raise `ApprovalDeniedError`, `ApprovalTimeoutError`, or `ApprovalPendingError` respectively. Skipped entirely when no handler is configured or the module does not require approval. See [Approval System](./approval-system.md).
 
-6. **Input Validation with Pydantic + Sensitive Field Redaction** -- The call's input payload is validated against the module's input schema (a dynamically generated Pydantic model). Fields annotated with `x-sensitive` are redacted from logs and error messages using the `redact_sensitive` utility.
+6. **Middleware Before Chain** -- All registered "before" middleware functions are executed in order. Each middleware receives the context and input, and may modify or enrich them before validation runs.
 
-7. **Middleware Before Chain** -- All registered "before" middleware functions are executed in order. Each middleware receives the context and validated input, and may modify or enrich them before the module runs.
+7. **Input Validation with Pydantic + Sensitive Field Redaction** -- The call's input payload (including any modifications from middleware) is validated against the module's input schema (a dynamically generated Pydantic model). Fields annotated with `x-sensitive` are redacted from logs and error messages using the `redact_sensitive` utility.
 
 8. **Module Execution with Timeout (Dual-Timeout Model)** -- The module's handler is invoked with dual-timeout enforcement: both a per-module timeout (`resources.timeout`, default 30s) and a global deadline (`executor.global_timeout`, default 60s). The shorter of the two is applied, preventing nested call chains from exceeding the global budget. The global deadline is set on the root call and propagated to child contexts via `Context._global_deadline`.
 
@@ -47,6 +47,18 @@ The executor processes every module call through the following pipeline:
 
 11. **Result Return** -- The final validated output (or error) is packaged into a structured result and returned to the caller.
 
+!!! info "Step Metadata"
+    Each pipeline step declares four metadata fields:
+
+    | Field | Type | Default | Purpose |
+    |-------|------|---------|---------|
+    | `match_modules` | glob patterns or null | `null` (all) | Only run this step for matching module IDs |
+    | `ignore_errors` | bool | `false` | If true, step failure logs warning and continues |
+    | `pure` | bool | `false` | If true, safe to run during `validate()` dry-run mode |
+    | `timeout_ms` | int | `0` | Per-step timeout in milliseconds (0 = no limit) |
+
+    These fields enable targeted step application, fault-tolerant pipelines, and dry-run validation without code changes.
+
 ### Key Classes
 
 - **Executor** -- The main engine class that implements the execution pipeline. Manages middleware registration, timeout configuration, and the execution loop.