[FEATURE]: decouple plugin execution mode from error handling

[araujof]

Description

Decouple plugin execution mode from error handling. Those two concepts are mixed together under PluginMode presently.

Plugin Modes

Each plugin declares a mode, which defines its authority level over pipeline execution and payload mutation.

class PluginMode(StrEnum):
    OBSERVE = "observe"
    ENFORCE = "enforce"
    PERMISSIVE = "permissive"

Modes are strictly hierarchical in authority:

OBSERVE  <  ENFORCE  <  PERMISSIVE

Each mode grants specific capabilities:

Mode	Can Observe	Can Modify	Can Deny	Pipeline Waits	Typical Use Cases
observe	Yes	No	No	No	Audit logging, telemetry, analytics
enforce	Yes	No	Yes	Yes	Authorization, policy enforcement, rate limiting
permissive	Yes	Yes (COW)	Yes	Yes	Redaction, normalization, header injection

Mode semantics

observe

• Receives a read-only (or copy-on-write) view of the payload
• Cannot modify or deny execution
• Executes asynchronously
• Results are ignored
• Used for side effects only

validate

• Receives a read-only (or copy-on-write) view of the payload
• May allow or deny execution
• Payload modifications are ignored
• Used for policy enforcement and validation

permissive

• Receives a mutable copy of the payload (copy-on-write)
• May modify, allow, or deny execution
• Modifications propagate to downstream plugins and the caller

Scheduling model (derived from mode)

Execution scheduling is determined automatically from mode:

• Observe plugins — Executed asynchronously. Never block the pipeline. May run in parallel.
• Enforce plugins — Executed in parallel. Pipeline waits for completion. Safe parallelism due to read-only access.
• Permissive plugins — Executed sequentially. Each plugin receives the output of the previous plugin. Ensures deterministic transformation order.

Plugin authors do not control scheduling directly. Scheduling is derived from mode to guarantee safety and correctness.

Mode progression and rollout

Modes support progressive deployment:

observe  →  enforce  →  permissive
 async      enforce      enforce + correct

This allows operators to:

• Start with observe mode to measure impact
• Promote to enforce mode to enforce policy
• Promote to permissive mode to automatically correct violations

Error Handling

Error handling behavior is controlled by the on_error attribute, independent of mode.

class OnError(StrEnum):
    FAIL = "fail"
    IGNORE = "ignore"
    DISABLE = "disable"

Value	Behavior
fail	Pipeline halts and error propagates
ignore	Error logged; pipeline continues
disable	Plugin automatically disabled after error

Default mode is fail.

Semantics

fail (default)

• Plugin failures raise a PluginError that wraps any undelying errors
• Ensures fail-safe enforcement
• Recommended for security-critical plugins

ignore

• Plugin failures are logged, no errors are propagated
• Pipeline continues execution
• Recommended for observability and non-critical plugins

disable

• Plugin failures are logged, no errors are propagated
• Pipeline continues execution
• Plugin is automatically transitioned to a disabled state
• Prevents repeated failures from affecting pipeline stability
• Useful for experimental or external plugins

Error isolation

Each plugin executes in isolation:

• Exceptions do not crash the host system
• Failures are contained to the plugin invocation
• Behavior is controlled exclusively by on_error

Example configuration:

plugins:
  - name: audit_logger
    mode: observe
    on_error: ignore

  - name: rbac_authorizer
    mode: enforce
    on_error: fail

  - name: pii_redactor
    mode: modify
    on_error: disable