refactor: execution modes

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

README.md

@@ -164,15 +164,26 @@ A plugin method can:
 
 ### Execution Modes
 
-Plugins run in phases in this order: `sequential` → `audit` → `concurrent` → `fire_and_forget`.
+Plugins run in phases in this order:
 
-| Mode | Execution | Can block? | State merged? | Use case |
-|------|-----------|:-----------:|:-------------:|---------|
-| `sequential` | One at a time, chained | Yes | Yes | Enforcement pipelines |
-| `audit` | One at a time, chained | No | No | Logging, monitoring |
-| `concurrent` | Parallel, fail-fast | Yes | Yes | Independent validations |
-| `fire_and_forget` | Background, after all phases | No | No | Telemetry, audit logs |
-| `disabled` | Not loaded | — | — | Plugin off |
+```
+sequential → transform → audit → concurrent → fire_and_forget
+```
+
+| Mode | Execution | Can block? | Can modify? | State merged? | Use case |
+|------|-----------|:-----------:|:-----------:|:-------------:|---------|
+| `sequential` | Serial, chained | Yes | Yes | Yes | Policy enforcement + transformation |
+| `transform` | Serial, chained | No | Yes | Yes | Data transformation (redaction, rewriting) |
+| `audit` | Serial | No | No | No | Logging, monitoring, metrics |
+| `concurrent` | Parallel, fail-fast | Yes | No | Yes | Independent policy gates |
+| `fire_and_forget` | Background, after all phases | No | No | No | Telemetry, audit logs |
+| `disabled` | Not loaded | — | — | — | Plugin off |
+
+- **`sequential`** plugins are awaited one at a time in priority order. Each receives the chained output of the previous plugin. Can halt the pipeline and modify payloads. Use for enforcement + transformation.
+- **`transform`** plugins are awaited one at a time after all sequential plugins. Can modify payloads but blocking attempts are suppressed. Use for data transformation pipelines (PII redaction, prompt rewriting) that should not have policy-enforcement power.
+- **`audit`** plugins are awaited one at a time after transform. Observe-only: payload modifications are discarded and violations are logged but do not block. Use for monitoring, auditing, and gradual rollout of policies.
+- **`concurrent`** plugins are dispatched in parallel after audit. Can halt the pipeline (fail-fast on first blocking result) but payload modifications are discarded to avoid non-deterministic last-writer-wins races. Use for independent policy gates.
+- **`fire_and_forget`** plugins are dispatched as background tasks after all other phases. They receive an isolated snapshot. Cannot block or modify. Use for telemetry and async side effects.
 
 Error handling is configured separately with `on_error`, independent of mode:
 
@@ -230,17 +241,17 @@ plugins:
 
 ### Priority
 
-Plugins are scheduled by mode, and execute in priority order within sequential bands (lower number = higher priority). Use this to ensure validation runs before transformation, and transformation runs before logging.
+Plugins are scheduled by mode, and execute in priority order within each phase (lower number = higher priority). Use this to ensure enforcement runs before transformation, and transformation runs before logging.
 
 **Plugin Scheduling**
 
-At each hook invocation, plugins are grouped and scheduled by execution modes, following a strict group order:
+At each hook invocation, plugins are grouped and scheduled by execution mode, following a strict phase order:
 
 ```
-sequential → audit → concurrent → fire_and_forget
+sequential → transform → audit → concurrent → fire_and_forget
 ```
 
-Within sequential and audit groups, plugins execute in **priority order** (lower number = higher priority, e.g., `10` runs before `20`).
+Within `sequential`, `transform`, and `audit` phases, plugins execute in **priority order** (lower number = higher priority, e.g., `10` runs before `20`).
 
 ### Conditions
 

cpex/framework/__init__.py

@@ -19,7 +19,7 @@
 # First-Party
 from cpex.framework.base import Plugin
 from cpex.framework.decorator import hook
-from cpex.framework.errors import PluginError, PluginFrameworkError, PluginViolationError
+from cpex.framework.errors import PluginError, PluginViolationError
 from cpex.framework.external.mcp.server import ExternalPluginServer
 from cpex.framework.hooks.agents import (
     AgentHookType,
@@ -163,7 +163,6 @@ def get_plugin_manager(
     "PluginContextTable",
     "PluginError",
     "PluginErrorModel",
-    "PluginFrameworkError",
     "PluginLoader",
     "PluginManager",
     "PluginMode",

cpex/framework/errors.py

@@ -13,32 +13,6 @@
 from cpex.framework.models import PluginErrorModel, PluginViolation
 
 
-class PluginFrameworkError(Exception):
-    """An error originating from the plugin framework itself (not from a plugin).
-
-    Raised when an internal framework operation fails — for example, when
-    payload isolation cannot deep-copy a value.
-
-    Attributes:
-        message (str): Description of the framework error.
-    """
-
-    def __init__(self, message: str):
-        """Initialize a plugin framework error.
-
-        Args:
-            message: Description of what went wrong.
-
-        Examples:
-            >>> from cpex.framework.errors import PluginFrameworkError
-            >>> err = PluginFrameworkError("cannot isolate payload")
-            >>> str(err)
-            'cannot isolate payload'
-        """
-        self.message = message
-        super().__init__(self.message)
-
-
 class PluginViolationError(Exception):
     """A plugin violation error.