[Design Discussion] Pre/ Post Execution Hooks for Flow Validations

[ThaminduDilshan]

Related Feature Issue

N/A

Problem Summary

Thunder flow engine currently relies on executors as the primary workers within a flow graph. Each executor is attached to a task execution node, and the flow definition (graph) explicitly wires nodes together. This works well for the core flow logic, but introduces friction for cross-cutting concerns — operations that need to run across many (or all) nodes/requests but don't belong in the per-node execution path. Some examples are;

• Input validators (format, length, encoding checks on user-supplied data)
• CAPTCHA / bot detection (must run before user input reaches any executor)
• Rate limiting / abuse prevention (per-request, per-flow, or per-node)

Following current pattern, implementing these as executors would require duplicating nodes throughout every flow definition, which is impractical. Some concerns (e.g., challenge token validation, permission validation, attribute uniqueness) are already handled through hardcoded checks in the engine or via special-purpose executors (PermissionValidator, AttributeUniquenessValidator), but there is no unified model for them.

We need a first-class abstraction that lets these cross-cutting concerns be declared once and engaged automatically at the right lifecycle points, without polluting every flow graph.

High-Level Approach

Naming note: This document uses the placeholder term "interceptor" throughout. The final name is an open question — see the naming poll at the end.

Introduce an interceptor abstraction — lightweight, focused processing units that execute at well-defined lifecycle points during flow execution. Interceptors are distinct from executors in that:

1. They are not nodes in the flow graph — they don't occupy graph positions or affect flow topology
2. They execute at lifecycle points managed by the engine, not through node traversal
3. They can be configured once at the flow level and selectively applied to specific nodes or all nodes

Lifecycle Points

Interceptors engage at specific points in the engine's execution lifecycle:

┌──────────────────────────────────────────────────────────────┐
│                     Flow Request Arrives                     │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │         PRE_REQUEST Interceptors                       │  │
│  │  (once per incoming request, before any node runs)     │  │
│  │  Examples: rate limiter, CAPTCHA, input sanitizer,     │  │
│  │           challenge token validation                   │  │
│  └──────────────────────┬─────────────────────────────────┘  │
│                         │                                    │
│  ┌──────────────────────▼─────────────────────────────────┐  │
│  │              Node Execution Loop                       │  │
│  │                                                        │  │
│  │  For each node:                                        │  │
│  │  ┌─────────────────────────────────────────────────┐   │  │
│  │  │      PRE_NODE Interceptors                      │   │  │
│  │  │  (before each node executes)                    │   │  │
│  │  │  Examples: permission validator,                │   │  │
│  │  │    attribute uniqueness validator               │   │  │
│  │  └────────────────────┬────────────────────────────┘   │  │
│  │                       │                                │  │
│  │  ┌────────────────────▼────────────────────────────┐   │  │
│  │  │       Node Execution (current behavior)         │   │  │
│  │  └────────────────────┬────────────────────────────┘   │  │
│  │                       │                                │  │
│  │  ┌────────────────────▼────────────────────────────┐   │  │
│  │  │      POST_NODE Interceptors                     │   │  │
│  │  │  (after each node completes)                    │   │  │
│  │  │  Examples: output sanitizer                     │   │  │
│  │  └─────────────────────────────────────────────────┘   │  │
│  │                                                        │  │
│  └──────────────────────┬─────────────────────────────────┘  │
│                         │                                    │
│  ┌──────────────────────▼─────────────────────────────────┐  │
│  │         POST_REQUEST Interceptors                      │  │
│  │  (once per request, after all node processing)         │  │
│  │  Examples: response enrichment                         │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Interceptor Categories

Category	Description	Examples
Default	Always enforced by the engine. Not configurable — they run unconditionally.	Challenge token validation, sensitive data cleanup, request context validation
Configurable	Declared in the flow definition. Flow author adds, configures, and scopes them to specific nodes.	CAPTCHA, input validators, rate limiting, attribute uniqueness validation, permission validation

Default interceptors are invisible in the flow definition and enforced in engine code. Configurable interceptors are explicitly declared and can be scoped to all nodes or selected nodes.

Architecture Overview

Interface

Interceptors follow the same Execute(ctx) → result pattern as executors, but with a narrower contract:

• They receive an InterceptorContext carrying the HTTP request context, flow state, current node info, and interceptor-specific properties
• They return a pass/fail result with an optional failure reason
• They can enrich the execution context via RuntimeData
• They cannot modify the flow graph, change node routing, or tamper with authentication state

Registration and Metadata

Interceptors register with an InterceptorRegistry at startup, mirroring the executor registry pattern. Each interceptor self-describes its metadata at registration:

Metadata	Purpose	Example values
Name	Unique identifier, referenced in flow definitions	"CaptchaInterceptor", "RateLimiter"
Modes	Supported modes	PRE_REQUEST, PRE_NODE, POST_NODE, POST_REQUEST
Category	Whether the engine enforces it or the flow author configures it	DEFAULT, CONFIGURABLE
Priority	Execution order within the same mode (lower = runs first)	100 (default), 200 (configurable)

Default interceptors always run. Configurable interceptors only run when declared in the flow definition.

Scoping

Configurable interceptors declare their scope in the flow definition:

• "scope": "ALL" — runs for every node
• "scope": "SELECTED" with "applyTo": [...] — runs only for listed nodes

Nodes can opt out of globally-scoped interceptors via "skipInterceptors" in their existing properties.

{
    "id": "some_internal_node",
    "type": "TASK_EXECUTION",
    "properties": {
        "skipInterceptors": ["InputValidator"]
    },
    "executor": {
        "name": "SomeExecutor"
    },
    "onSuccess": "end"
}

Engine Integration

The engine invokes interceptors at each lifecycle point within the existing execution loop. Default interceptors always run; configurable ones run only when declared in the flow definition. Failure at any point halts execution and returns error to the client.

Execute(ctx):
    runInterceptors(PRE_REQUEST, ctx)
    
    for each node:
        runInterceptors(PRE_NODE, ctx, node)
        node.Execute(ctx)
        runInterceptors(POST_NODE, ctx, node)
    
    runInterceptors(POST_REQUEST, ctx)

Configurable interceptors are declared as a top-level interceptors array alongside nodes. They use properties for configuration (same pattern as nodes). Nodes opt out of globally-scoped interceptors via their existing properties field.

{
    "name": "Default Basic Authentication Flow",
    "handle": "default-basic-flow",
    "flowType": "AUTHENTICATION",
    "interceptors": [
        {
            "name": "CaptchaInterceptor",
            "mode": "PRE_NODE",
            "scope": "SELECTED",
            "applyTo": ["prompt_credentials"],
            "properties": {
                "provider": "recaptcha",
                "siteKey": "..."
            }
        },
        {
            "name": "RateLimiter",
            "mode": "PRE_REQUEST",
            "scope": "ALL",
            "properties": {
                "maxAttempts": 5,
                "windowSeconds": 300
            }
        }
    ],
    "nodes": [
        {
            "id": "start",
            "type": "START",
            "onSuccess": "prompt_credentials"
        },
        {
            "id": "prompt_credentials",
            "type": "PROMPT",
            "meta": { "..." : "..." },
            "prompts": [
                {
                    "inputs": [
                        {
                            "ref": "input_001",
                            "identifier": "username",
                            "type": "TEXT_INPUT",
                            "required": true
                        },
                        {
                            "ref": "input_002",
                            "identifier": "password",
                            "type": "PASSWORD_INPUT",
                            "required": true
                        }
                    ],
                    "action": {
                        "ref": "action_001",
                        "nextNode": "basic_auth"
                    }
                }
            ]
        },
        {
            "id": "basic_auth",
            "type": "TASK_EXECUTION",
            "executor": {
                "name": "BasicAuthExecutor"
            },
            "onSuccess": "authorization_check",
            "onIncomplete": "prompt_credentials"
        },
        {
            "id": "authorization_check",
            "type": "TASK_EXECUTION",
            "executor": {
                "name": "AuthorizationExecutor"
            },
            "onSuccess": "auth_assert"
        },
        {
            "id": "auth_assert",
            "type": "TASK_EXECUTION",
            "properties": {
                "skipInterceptors": ["RateLimiter"]
            },
            "executor": {
                "name": "AuthAssertExecutor"
            },
            "onSuccess": "end"
        },
        {
            "id": "end",
            "type": "END"
        }
    ]
}

Key points in this example:

• CaptchaInterceptor runs PRE_NODE, scoped only to prompt_credentials — it validates the CAPTCHA before the prompt node processes user input
• RateLimiter runs PRE_REQUEST for all requests — but auth_assert opts out via skipInterceptors in its properties
• Default interceptors (challenge token, sensitive data cleanup) run automatically without being declared here

Existing Patterns That Become Interceptors

Several existing mechanisms would be unified under this model:

Current Implementation	Interceptor Equivalent	Category	Mode
validateChallengeToken() in engine	ChallengeTokenInterceptor	Default	PRE_REQUEST
clearSensitiveInputs() in engine	SensitiveDataInterceptor	Default	POST_NODE
PermissionValidator executor	PermissionInterceptor	Configurable	PRE_NODE
AttributeUniquenessValidator executor	UniquenessInterceptor	Configurable	PRE_NODE

Security Considerations

• Interceptor ordering matters: Interceptors within the same mode execute in priority order (ascending) as declared during registration. Default interceptors register with lower priority values to ensure they always run first. For configurable interceptors with equal priority, declaration order in the flow definition is the tiebreaker.
• Default interceptors cannot be bypassed: The engine guarantees that default interceptors (like challenge token validation) always execute, regardless of flow definition configuration or node-level skipInterceptors.
• Context isolation: Interceptors have read access to the context but limited write access. They cannot modify the flow graph, change node routing, or tamper with authentication state. Only RuntimeData enrichment is permitted.
• Sensitive data in properties: Interceptor properties containing secrets (API keys) stored in flow definitions must follow the same encryption/protection patterns used for other sensitive configuration.

Impacted Areas

• Flow Engine (flowexec/engine.go) — Interceptor invocation points in the execution loop
• Flow Core (flow/core/) — InterceptorInterface, InterceptorContext, InterceptorResult definitions
• Flow Interceptor (flow/interceptor/) — NEW package with registry, init, and interceptor implementations
• Flow Definition Model (flow/mgt/model.go) — InterceptorDefinition struct and interceptors field on FlowDefinition
• Graph Builder (flow/mgt/graph_builder.go) — Parsing interceptor definitions from flow definitions
• Flow Builder UI — Visual representation and configuration of interceptors in the flow composer
• Executor Package (flow/executor/) — Migration of PermissionValidator and AttributeUniquenessValidator to flow/interceptor/

Alternatives Considered

Alternative 1: Keep validators as executors with special handling

• Pros: No new abstraction needed, works within current model
• Cons: Requires duplicating executor nodes in every flow; no clean separation of per-request vs per-node concerns; pain point grows as more validators are needed

Alternative 2: Middleware-style pipeline (wrap the entire engine)

• Pros: Familiar pattern from HTTP middleware; clean for per-request concerns
• Cons: Doesn't handle per-node scoping well; too coarse-grained for node-level validators

Alternative 3: Implicit executor chains (engine auto-inserts hidden nodes)

• Pros: Reuses existing executor infrastructure; no new interface
• Cons: Hidden graph mutations are confusing; execution history shows phantom nodes

Questions for Community Input

1. Naming — Pick the term that best communicates the intent for this abstraction:

   Candidate	Reasoning
   Guard	Implies protection/gatekeeper — strong for validation use cases, but may feel narrow if used for non-security concerns
   Interceptor	Generic, well-known in Java EE / Spring — implies catching requests in transit
   Policy	Implies declarative rules — common in authz/cloud contexts (OPA, Kubernetes)
   Filter	Familiar from Servlet Filters — implies selection/validation, but may imply data transformation
   Checkpoint	Implies a validation gate — clear for pre-execution checks, but less intuitive for post-execution

2. Mode vs Hook — For the lifecycle point field on the interceptor definition, should we use "mode" (consistent with executor definitions) or "hook" (more semantically explicit about lifecycle engagement)?

3. UX of flow builder UI, mainly how are we going to represent validators in the flow configuration UI.

[ThaminduDilshan]

Implementation Details

Package Structure

A new flow/interceptor package alongside the existing flow/executor, following the same organizational pattern:

backend/internal/flow/
├── common/              # Shared constants and models (existing)
├── core/                # Graph, node, executor interfaces (existing)
│   ├── interceptor.go   # NEW — InterceptorInterface, InterceptorContext, InterceptorResult
│   └── ...              
├── executor/            # Executor implementations and registry (existing)
├── interceptor/         # NEW — Interceptor implementations and registry
│   ├── init.go          # Initialize() — registers all interceptors
│   ├── registry.go      # InterceptorRegistry implementation
│   ├── constants.go     # Interceptor names, mode constants, priorities
│   ├── challenge_token_interceptor.go   # Default: PRE_REQUEST
│   ├── sensitive_data_interceptor.go    # Default: POST_NODE
│   ├── permission_interceptor.go        # Configurable: PRE_NODE
│   ├── uniqueness_interceptor.go        # Configurable: PRE_NODE
│   └── ...
├── flowexec/            # Engine and service (existing — adds interceptor hooks)
├── flowmeta/            # Flow metadata service (existing)
└── mgt/                 # Flow management and graph builder (existing)

Interceptor Interface

An interceptor follows a contract similar to executors — with an Execute method — but with a narrower, validation-focused context:

// InterceptorInterface defines the interface for flow interceptors.
type InterceptorInterface interface {
    // Execute runs the interceptor logic and returns a result.
    Execute(ctx *InterceptorContext) (*InterceptorResult, error)

    // Other common methods. Can decide which are required at the implementation time.
    GetName() string
    GetMode() InterceptorMode
    GetCategory() InterceptorCategory
    GetPriority() int
}

The interceptor context carries the execution state and the HTTP request context:

// InterceptorContext holds the context available to an interceptor during execution.
type InterceptorContext struct {
    // Context carries the HTTP request context (includes request metadata,
    // permissions, trace IDs, etc.)
    Context context.Context

    // Flow-level fields
    ExecutionID   string
    FlowType      common.FlowType
    AppID         string
    UserInputs    map[string]string
    RuntimeData   map[string]string
    Application   appmodel.Application

    // Node-level fields (nil for PRE_REQUEST/POST_REQUEST interceptors)
    CurrentNodeID string
    NodeType      common.NodeType

    // Interceptor-specific properties (from flow definition)
    Properties map[string]interface{}

    // Authenticated user state
    AuthenticatedUser authncm.AuthenticatedUser
    ExecutionHistory  map[string]*common.NodeExecutionRecord
}

The result is pass/fail with optional context enrichment:

// InterceptorResult holds the outcome of an interceptor execution.
type InterceptorResult struct {
    // Status indicates whether the interceptor passed or failed.
    Status InterceptorStatus // PASS or FAIL

    // FailureReason provides a human-readable reason when Status is FAIL.
    FailureReason string

    // RuntimeData allows interceptors to enrich the execution context
    // (e.g., set metadata for downstream nodes).
    RuntimeData map[string]string
}

Key constraints:

• Interceptors cannot modify the flow graph topology or change what node executes next
• Interceptors cannot tamper with authentication state
• Interceptors can enrich the execution context via RuntimeData

Registration and Metadata

Interceptors register with an InterceptorRegistry during initialization, following the same pattern as executor registration. Each interceptor self-describes its metadata at registration time — the engine uses this metadata to determine when and in what order to run each interceptor.

// InterceptorRegistryInterface defines registry operations for interceptors.
type InterceptorRegistryInterface interface {
    RegisterInterceptor(interceptor InterceptorInterface)
    GetInterceptors(mode InterceptorMode) []InterceptorInterface
    GetInterceptor(name string) (InterceptorInterface, error)
    IsRegistered(name string) bool
}

The registry groups interceptors by mode and sorts them by priority within each group. At initialization time, all interceptors register themselves with their metadata:

// Initialize registers available interceptors and returns the interceptor registry.
func Initialize(
    flowFactory core.FlowFactoryInterface,
    // ... service dependencies
) InterceptorRegistryInterface {
    reg := newInterceptorRegistry()

    // Default interceptors (always enforced, high priority)
    reg.RegisterInterceptor(newChallengeTokenInterceptor(...))
    reg.RegisterInterceptor(newSensitiveDataInterceptor(...))

    // Configurable interceptors (engaged via flow definition)
    reg.RegisterInterceptor(newPermissionInterceptor(flowFactory))
    reg.RegisterInterceptor(newUniquenessInterceptor(flowFactory, userSchemaService, userProvider))
    reg.RegisterInterceptor(newCaptchaInterceptor(...))
    reg.RegisterInterceptor(newRateLimiterInterceptor(...))

    return reg
}

Each interceptor declares its metadata through the interface methods:

Metadata	Purpose	Example values
Name	Unique identifier, referenced in flow definitions	"CaptchaInterceptor", "RateLimiter"
Modes	Supported modes	PRE_REQUEST, PRE_NODE, POST_NODE, POST_REQUEST
Category	Whether the engine enforces it or the flow author configures it	DEFAULT, CONFIGURABLE
Priority	Execution order within the same mode (lower = runs first)	100 (default), 200 (configurable)

The engine uses this metadata at runtime:

• Default interceptors always run at their declared mode, regardless of flow definition. They cannot be skipped via skipInterceptors.
• Configurable interceptors only run when declared in the flow definition's interceptors array. The flow definition provides the scope/applyTo and runtime properties.
• Within the same mode, interceptors execute in priority order (ascending). Default interceptors typically register with lower priority values so they run before configurable ones.

Interceptor Engagement Model

Per-Request Interceptors (mode: PRE_REQUEST / POST_REQUEST):

• Execute once per incoming API request, regardless of how many nodes the engine processes
• Receive the engine context (with context.Context carrying the HTTP request)
• CurrentNodeID and NodeType are empty in the interceptor context
• Suitable for rate limiting, CAPTCHA validation, response enrichment

Per-Node Interceptors (mode: PRE_NODE / POST_NODE):

• Execute before/after each individual node in the execution loop
• Receive both engine context and current node info
• Can be scoped to all nodes or selected nodes
• Suitable for permission validation, input validation

Node Scoping for Per-Node Interceptors

Configurable interceptors specify their scope in the flow definition:

• "scope": "ALL" — runs for every node in the flow
• "scope": "SELECTED" with "applyTo": [...] — runs only for the listed node IDs

Nodes can opt out of globally-scoped interceptors via their existing properties field:

{
    "id": "some_internal_node",
    "type": "TASK_EXECUTION",
    "properties": {
        "skipInterceptors": ["InputValidator"]
    },
    "executor": {
        "name": "SomeExecutor"
    },
    "onSuccess": "end"
}

Engine Integration

The interceptor execution is woven into the existing engine loop:

Execute(ctx):
    runInterceptors(PRE_REQUEST, ctx)             ← NEW
    
    for each node:
        runInterceptors(PRE_NODE, ctx, node)      ← NEW
        node.Execute(ctx)                         ← existing
        runInterceptors(POST_NODE, ctx, node)     ← NEW
    
    runInterceptors(POST_REQUEST, ctx)            ← NEW

Interceptor failure at any point halts execution and returns an appropriate error response to the client.

[anushasunkada]

@ThaminduDilshan

I think we should consider taking the interceptors to register from configuration. So the embedder application can consider to configure only required interceptors - Similar concept we are planning with executor registry.

[ThumulaPerera]

Small clarification regarding

RateLimiter runs PRE_REQUEST for all requests — but auth_assert opts out via skipInterceptors in its properties

If the interceptor is PRE/POST_REQUEST what does it mean for a executor to be able to skip it ? AFAIU this should not be allowed

[NutharaNR]

Implementation Update: Changes from Proposed Design

While the core design from this discussion is preserved, several refinements were made during implementation to better align with existing engine patterns and address practical concerns. Below is a summary of the key changes.

Interface Restructuring: Interceptor vs. InterceptorUnit

The proposal defined a single InterceptorInterface carrying mode, category, and priority. The implementation splits this into two interfaces:

• InterceptorInterface: Holds only the execution logic (Execute), identity (GetName), enforcement flag (IsDefault), and ordering (GetPriority).
• InterceptorUnitInterface: Binds an interceptor to a lifecycle configuration, carrying mode, scope, applyTo list, and properties.

This separation allows the same interceptor to operate at multiple lifecycle points without duplication. For example, ChallengeTokenInterceptor registers once but is bound to both PRE_REQUEST (validation) and POST_REQUEST (rotation) as two distinct units.

Category Simplified to Boolean

The proposed InterceptorCategory enum (DEFAULT, CONFIGURABLE) is replaced with an IsDefault() bool method on InterceptorInterface. This avoids introducing a type for what is effectively a binary distinction.

Three-State Response Model

The proposed InterceptorResult used a binary PASS/FAIL status. The implementation introduces a three-state InterceptorResponse:

Status	Meaning
COMPLETE	Interceptor passed; continue execution
INCOMPLETE	Interceptor needs client interaction (e.g., CAPTCHA prompt); pause flow
FAIL	Interceptor rejected the request; the flow instance concludes with error

INCOMPLETE is only valid for per-node modes (PRE_NODE, POST_NODE). Request-level modes (PRE_REQUEST, POST_REQUEST) treat INCOMPLETE as an execution error, since there is no meaningful way to pause at the request boundary. Hence either the request level interception complete successfully or fail the request with error.

The response also carries structured fields beyond a simple failure reason:

type InterceptorResponse struct {
    Status         InterceptorStatus
    Error          *serviceerror.ServiceError
    EngineOutputs  map[string]string
    ChallengeToken string
    FieldErrors    []FieldError
}

• EngineOutputs feeds data back into the engine's runtime context.
• FieldErrors provides field-level validation errors for the UI.
• ChallengeToken carries the rotated token in the response.

SharedData for Cross-Request State

The proposed InterceptorContext included runtime data for enrichment. The implementation adds a dedicated SharedData map[string]string field that persists across multiple requests within a single flow instance. This is essential for stateful interceptors like challenge token validation, where the token hash generated in one request must be available for verification in the next.

Registry Scope Change

The proposal's registry supported mode-based lookups (GetInterceptors(mode)). The implementation simplifies the registry to name-based registration and lookup only:

type InterceptorRegistryInterface interface {
    RegisterInterceptor(name string, interceptor InterceptorInterface)
    GetInterceptor(name string) (InterceptorInterface, error)
    IsRegistered(name string) bool
}

Mode-based filtering and scope resolution are handled at runtime by the interceptor runner during resolveApplicableInterceptors, keeping the registry focused on identity and instance management.

Configuration-Driven Registration

The proposal hardcoded all interceptor registrations in Initialize(). The implementation reads a flow.interceptors configuration list:

configuration:
  flow:
    interceptors: []  # empty = register all built-in interceptors

When the list is empty, all known built-in interceptors are registered. When populated, only the listed interceptors are initialized. This gives deployers control over which interceptors are active without code changes.

Default Interceptors as Pre-Built Units

Default interceptors are defined as pre-built InterceptorUnit instances in defaults.go, rather than being constructed dynamically. The runner injects these alongside flow-configured interceptors during resolution, ensuring they always execute regardless of what a flow definition declares.

Challenge Token: Dual-Mode Interceptor

The proposal listed ChallengeTokenInterceptor as a single PRE_REQUEST interceptor. The implementation registers it at two lifecycle points:

• PRE_REQUEST: Validates the incoming token against the stored hash. Skips validation on the first request (no stored hash) and when the node's execution policy allows it (e.g., segment restarts).
• POST_REQUEST: Generates a new secure token, stores its hash in SharedData, and returns the plaintext token to the client via the response. Targets applyOnStatuses: ["COMPLETE", "INCOMPLETE"] interceptor property, so token rotation is skipped on error exits where no client response carrying a new token would be useful.

Context Adjustments

The InterceptorContext diverges from the proposal in several fields:

Proposed	Implemented	Reason
RuntimeData map[string]string	SharedData map[string]string	Renamed to clarify cross-request persistence semantics
Application	Removed	Not needed by current interceptors
ExecutionHistory	Removed	Not needed by current interceptors
—	ForwardedData map[string]interface{}	Carries data forwarded between nodes
—	AdditionalData map[string]string	Carries supplementary engine data
—	AllowSegmentRestart bool	Signals segment restart mode to interceptors
—	CurrentNode NodeInterface	Full node interface instead of just ID and type

Scope: Only ChallengeTokenInterceptor Implemented

This phase focuses on the core interceptor framework and the ChallengeTokenInterceptor as the first default interceptor. The remaining interceptors from the proposal (SensitiveDataInterceptor, PermissionInterceptor, UniquenessInterceptor, CaptchaInterceptor, RateLimiter) are not yet implemented.

Database Schema

A new INTERCEPTORS column (JSONB on PostgreSQL, TEXT on SQLite) is added to the FLOW_VERSION table to persist InterceptorDefinition arrays alongside flow node definitions.

[NutharaNR]

Core feature implementation issue: #3122

[NutharaNR]

Interceptors can have predefined, non-configurable inputs, but these inputs must arrive through the flow data. That is, the inputs should already be present in the flow context, collected by prompt nodes or other upstream graph participants. Interceptors process whatever data is available to them; they do not request missing data from the flow execution. An interceptor will not prompt the user to supply it.

Instead, the prompt node that an interceptor is applied to is responsible for ensuring the interceptor's inputs are collected. For example, if a captcha interceptor requires a captcha_token, then the prompt node it is attached to should declare captcha_token as a required input. The prompt node verifies the input is present before execution proceeds, so by the time the captcha interceptor runs, the token is guaranteed to be available.