[Design Discussion] Cross-Flow Invocation via a Call Node

[ThaminduDilshan]

Related Feature Issue

#2025

Problem Summary

The flow engine today executes a single self-contained graph per flow/execute invocation. Real-world identity journeys, however, frequently need to cross flow boundaries — a user on a sign-in page who chooses to register, an SMS OTP login that converts into an SMS OTP signup when the subscriber is unknown, or a recovery flow that should land the user authenticated on completion. We currently somewhat work around this on the frontend (e.g. the RICH_TEXT "Sign up" link on the credentials prompt) which leaves the backend unaware of the transition and prevents shared state, auto-login, and reusable journey composition. We need a first-class way to express "continue execution in another flow and return here" inside a flow definition.

High-Level Approach

Introduce a new node type — CALL — that references another flow and, when reached, transfers execution into that flow. When the called flow completes, control returns to the caller and follows the call node's outgoing edge, which may point to any node in the caller graph (including end or the caller's auth_assert node).

Key characteristics:

• A call node is a non-prompting, non-executor control-flow primitive. A CALL node carries a flow block with a mandatory ref (the referenced flow id/handle) field.
• Calls compose: a called flow may itself contain call nodes, forming a stack of frames. A maximum depth is enforced.
• The called flow's START and END are treated as transparent boundaries — control re-enters the caller after the callee's END.
• Edges on a CALL node: onSuccess is required (the node must connect somewhere on success), onFailure is optional (when absent, a failed call terminates the execution, matching how other nodes behave today). onIncomplete is not applicable to CALL nodes.
• Context is split into a shared scope and a per-frame scope. Identity-bearing data (user inputs, authenticated user, application, execution history) lives in shared scope and crosses the boundary without explicit wiring. Per-flow execution state (current graph, current node, segment, flow type) lives in the frame and is snapshotted on call / restored on return. Runtime data is per-key — executors decide whether their values are shared or frame-local at the point of writing.
• The registration flow no longer needs to embed AuthAssertExecutor to support auto-login (the caller can route the call node's onSuccess into its own auth_assert). Embedding it inside the callee is still permitted — that is a flow-design choice. The same observation applies to any executor: when a callee runs an executor that the caller also runs, the second invocation simply sees what the first wrote into shared scope.

Architecture Overview

Engine Execution at a Glance

The flow engine, today, walks one graph node-by-node against a single EngineContext. With CALL nodes, the engine maintains a stack of frames; each frame holds the per-flow execution state (graph, current node, segment, runtime data, etc.), while shared journey-level state (user inputs, authenticated user, application, execution history) lives once on the context and crosses frames freely.

The engine executes call node's Execute() method just like any other node. Aligning with the existing pattern, the call/return mechanics live inside the CALL node implementation. The engine's only added responsibility is response post-processing: when it observes a "switch flow" response or a callee END, it manipulates the frame stack accordingly.

In simple terms, on each step:

• For PROMPT or TASK_EXECUTION — unchanged from today.
• For a CALL node — the node's Execute() resolves the referenced flow (subject to the application-scoping check), validates the depth limit, and returns a response that the engine post-processes by pushing the current frame (recording the CALL node as its resume point) and switching the active frame to a new one rooted at the callee's START.
• For an END node — the engine recognises terminal status as it does today. If the frame stack is empty, the execution completes. Otherwise it pops the caller frame, looks up the recorded CALL node, and continues along that node's onSuccess edge (or onFailure if the callee ended in failure and the caller's CALL node defined one; if onFailure is absent on a failed callee, execution terminates as it would today for any failed node).
• A maximum call depth (a hardcoded code-level constant) is enforced by the CALL node's Execute() before it asks the engine to push a frame.

CALL Node Interface

The CALL node has its own typed interface alongside PromptNode and TaskExecutionNode. New fields are kept private and exposed via getters/setters:

type CallNode interface {
    NodeInterface

    GetReferencedFlow() string

    // Edges. onSuccess is required on a CALL node; onFailure is optional
    // (a missing onFailure terminates execution on call failure).
    GetOnSuccess() string
    GetOnFailure() string
}

The flow block in JSON deserializes into a private struct on the node, accessed via GetReferencedFlow(). onIncomplete is not applicable to CALL nodes and is not part of the interface.

Flow Definition Structure

Field naming below (flow, ref) is illustrative and open for refinement during implementation.

{
    "id": "call_registration",
    "type": "CALL",
    "flow": {
        "ref": "default-registration-flow"
    },
    "onSuccess": "auth_assert",
    "onFailure": "prompt_credentials"
},

Engine Context — Shared and Per-Frame

EngineContext is split into a shared scope and a stack of frames. New/modified fields are kept private and exposed through accessor methods (existing fields can migrate over time; for this change we apply the convention only to fields touched by the call-node work).

// EngineContext — accessor sketch (private fields, public getters/setters).
type EngineContext struct {
    // ---------- Shared scope (single instance, not snapshotted on call) ----------
    // - userInputs, sharedRuntimeData
    // - authenticatedUser, authUser, assertion
    // - executionHistory  (shared — required for cross-frame audit and go-back)
    // - application, executionId, traceId, verbose, challenge tokens
    // ...
    // ---------- Frame stack ----------
    // - currentFrame, frameStack (pushed on CALL, popped on callee END)
}

func (c *EngineContext) UserInputs() map[string]string
func (c *EngineContext) SetUserInput(key, value string)

func (c *EngineContext) RuntimeData(key string) (value string, ok bool)
func (c *EngineContext) SetRuntimeData(key, value string, shared bool)

func (c *EngineContext) AuthenticatedUser() authncm.AuthenticatedUser
func (c *EngineContext) SetAuthenticatedUser(u authncm.AuthenticatedUser)

func (c *EngineContext) ExecutionHistory() map[string]*common.NodeExecutionRecord
func (c *EngineContext) AppendHistory(rec *common.NodeExecutionRecord)

// Per-frame.
type Frame struct {
    // - graph, flowType
    // - currentNode, currentNodeResponse, currentAction, currentSegmentId
    // - runtimeData (frame-local), forwardedData, additionalData
    // - resumeCallNodeId (caller frames only)
}

func (f *Frame) Graph() core.GraphInterface
func (f *Frame) FlowType() common.FlowType
func (f *Frame) CurrentNode() core.NodeInterface
func (f *Frame) SetCurrentNode(n core.NodeInterface)
// ...

Why each field sits where it does:

• Shared — userInputs, authenticatedUser / authUser, assertion, application, executionHistory. These describe the user and the journey-as-a-whole; sharing them is the expectation.
• Per-frame — graph, flowType, currentNode, currentSegmentId, currentAction, forwardedData, additionalData. These describe what one specific flow is currently doing and must swap on call / restore on return.
• Runtime data — per-key, executor-controlled. SetRuntimeData(key, value, shared bool) lets the executor choose. The choice belongs to the executor because it knows which of its outputs are flow-local mechanics and which are journey-level. RuntimeData(key) reads frame-local first, then falls back to shared.
• Execution id — executionId is unchanged across the chain; one execution spans the whole call tree. The persisted flow context (FlowContextDB) is extended to carry the frame stack so suspended/resumed executions reconstruct call state.

Cycles and Depth

• Cycles between flows are allowed. Sign-in calling sign-up; the only requirement is that there exists at least one path from START that leads to an END. The graph builder validates reachability of an END and the existence of every referenced flow at construction time. (Until a dedicated flow validator lands, this is the graph builder's responsibility.)
• Depth is enforced at runtime against MAX_CALL_DEPTH, a code-level constant. A request that would exceed it fails the call.

Application Scoping (Phase 1)

Flows are executed against an application, and applications have a defined set of flow types attached (e.g. an authentication flow + a registration flow + a recovery flow). A CALL node may only invoke a flow that is attached to the same application — this is a runtime check (the flow being constructed does not know which applications will use it).

For phase 1, this design further restricts call targets to a different flow type from the caller. Same-type sub-flow calls (e.g. an authentication flow calling another authentication flow as a sub-routine) are deferred to phase 2, where we need to choose between two approaches:

• Allow an application to attach multiple flows of the same type, with one designated as primary
• Introduce a dedicated sub-flow concept — a flow that cannot be started directly via flow/execute and exists only to be referenced from another flow.

Security Considerations

• Flow reference integrity: referenced flow ids are resolved based on config time flow definition; the client at runtime never controls which flow is invoked.
• Application-scoped invocation: a CALL node may only invoke a flow that is attached to the same application as the executing flow. Calling an arbitrary flow id is rejected. This prevents an application from invoking unauthorized/ unrelated flow.
• Frame-local runtime data by default: executor-written runtime data is frame-local unless the executor explicitly publishes into shared scope.

Impacted Areas

• Flow execution engine and node model
• Flow definition schema and bootstrap flows
• Flow Builder UI (palette, canvas rendering, cross-flow navigation)
• Existing bootstrap flows that currently embed AuthAssertExecutor inside registration
• Frontend Login Gate behaviour for the "Sign up" affordance (rich text → action that posts to flow/execute)

Alternatives Considered

Alternative 1 — Inline-merge referenced graphs at runtime into a single composite graph

• Pros: a single graph at execution time; no frame stack; simpler engine loop.
• Cons: ambiguity around node-id collisions, duplicated nodes when the same flow is called from multiple sites, harder to keep callee context isolated, and tracing/auditing loses the natural "this happened inside flow X" framing. Editing the callee independently complicates cache invalidation of the merged form.
• Decision: Rejected. The frame-stack model is closer to how callers reason about composition, and it keeps each flow definition the unit of authoring, validation, and observability.

Alternative 2 — Generalise TASK_EXECUTION with a "SubFlowExecutor"

• Pros: no new node type.
• Cons: executors are intended for actual work (auth, validation, provisioning); flow invocation is control flow, not work. Overloading the executor abstraction muddies both. Validation, builder UX, and authoring all benefit from a dedicated node type.
• Decision: Rejected.

Sub-Decision: Cross-frame data passing

An explicit input/output contract on the call node was considered for the data-passing aspect specifically. It would offer strict, statically validated data flow, but forces every flow designer to enumerate what crosses the boundary even though the common answers (user identity, already-collected inputs, history) are always the same. We chose the shared / per-frame split described in Architecture Overview instead.

Questions for Community Input

1. For the phase 2 same-flow-type calling problem, which direction is preferred — multiple flows of the same type attached per application (with one primary), or a dedicated sub-flow concept that exists only to be referenced and cannot be started directly?

[ThaminduDilshan]

Example Usages

1. Sign-up from sign-in. A user lands on the credentials prompt and clicks "Sign up". Today this is a frontend-only RICH_TEXT link; with a CALL node, the action navigates the engine into a registration flow. On completion the caller's auth_assert runs and the user is logged in. The frontend "Sign up" affordance becomes a regular submit action that posts to flow/execute, with the rich-text concept retained purely for presentation/meta.

2. SMS OTP login → auto signup. The login flow collects a mobile number, verifies the sms otp, looks up the user, and on user-not-found prompts whether to register. If the user accepts, the engine calls into a regular registration flow. Because UserInputs is shared, the callee does not re-prompt for the mobile. On completion the caller proceeds to auth_assert and the user is auto-logged-in.

3. Recovery from sign-in. A user enters credentials, fails, clicks "Forgot password", and the engine calls into a recovery flow (e.g. email-invite link reset, or in-tab SMS OTP reset). For an in-tab recovery completing on the same browser tab, returning into the caller's auth_assert produces an auto-login at the end of recovery. For an out-of-band recovery (email link), the callee terminates without auth and the caller can route to an appropriate end state.

4. Combined parent login flow. A site that supports both customer and employee logins composes a thin parent flow: a single audience prompt, then two CALL nodes pointing at customer-login-flow and employee-login-flow. Each child flow stays independently authorable and testable.

---

Sample Flow Definitions

1. Authentication flow with a "Sign up" affordance that calls into the registration flow and returns to auth_assert

{
    "name": "Basic Authentication with Inline Signup",
    "handle": "auth-flow-with-signup",
    "flowType": "AUTHENTICATION",
    "nodes": [
        {
            "id": "start",
            "type": "START",
            "onSuccess": "prompt_credentials"
        },
        {
            "id": "prompt_credentials",
            "type": "PROMPT",
            "meta": {
                "components": [
                    {
                        "type": "BLOCK",
                        "id": "block_001",
                        "components": [
                            {
                                "id": "input_001",
                                "ref": "username",
                                "type": "TEXT_INPUT",
                                "required": true
                            },
                            {
                                "id": "input_002",
                                "ref": "password",
                                "type": "PASSWORD_INPUT",
                                "required": true
                            },
                            {
                                "type": "ACTION",
                                "id": "action_signin",
                                "variant": "PRIMARY",
                                "eventType": "SUBMIT"
                            }
                        ]
                    },
                    {
                        "type": "ACTION",
                        "id": "action_signup",
                        "variant": "TEXT",
                        "eventType": "SUBMIT"
                    }
                ]
            },
            "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_signin",
                        "nextNode": "basic_auth"
                    }
                },
                {
                    "action": {
                        "ref": "action_signup",
                        "nextNode": "call_registration"
                    }
                }
            ]
        },
        {
            "id": "basic_auth",
            "type": "TASK_EXECUTION",
            "executor": {
                "name": "BasicAuthExecutor"
            },
            "onSuccess": "auth_assert",
            "onIncomplete": "prompt_credentials"
        },
        {
            "id": "call_registration",
            "type": "CALL",
            "flow": {
                "ref": "default-registration-flow"
            },
            "onSuccess": "auth_assert"
        },
        {
            "id": "auth_assert",
            "type": "TASK_EXECUTION",
            "executor": {
                "name": "AuthAssertExecutor"
            },
            "onSuccess": "end"
        },
        {
            "id": "end",
            "type": "END"
        }
    ]
}

The registration flow referenced here no longer carries its own AuthAssertExecutor — auto-login is the caller's responsibility, achieved by wiring the call node's onSuccess into auth_assert. The subject created by registration crosses the frame boundary because AuthenticatedUser is shared by default.

2. Combined parent login flow that delegates to per-audience subflows

{
    "name": "Combined Login (Customer or Employee)",
    "handle": "combined-login",
    "flowType": "AUTHENTICATION",
    "nodes": [
        {
            "id": "start",
            "type": "START",
            "onSuccess": "prompt_audience"
        },
        {
            "id": "prompt_audience",
            "type": "PROMPT",
            "prompts": [
                {
                    "action": {
                        "ref": "as_customer",
                        "nextNode": "call_customer_login"
                    }
                },
                {
                    "action": {
                        "ref": "as_employee",
                        "nextNode": "call_employee_login"
                    }
                }
            ]
        },
        {
            "id": "call_customer_login",
            "type": "CALL",
            "flow": {
                "ref": "customer-login-flow"
            },
            "onSuccess": "end"
        },
        {
            "id": "call_employee_login",
            "type": "CALL",
            "flow": {
                "ref": "employee-login-flow"
            },
            "onSuccess": "end"
        },
        {
            "id": "end",
            "type": "END"
        }
    ]
}

Here both child flows handle their own auth_assert internally, and the caller is just a router. This shows that the call node does not require the caller to own assertion — both arrangements are valid.

[senthalan]

With this change,

1. The application will have reference to one flow. Within that flow there will be sub flows for register or recovery. (So we need to rename the application configuration)
2. Do we need the flowType category ? I don't think type will make much meaning of this in the runtime flow.
3. We had the capability to infer the registration flow from the authentication flow. What will happen to this feature with this change ?

[ThaminduDilshan]

1. The application will have reference to one flow. Within that flow there will be sub flows for register or recovery. (So we need to rename the application configuration)

This is not covered in this design/ improvement. This improvement just enables flow references, this needs to be taken with a separate effort. There were some conflicting ideas for this last time.

2. Do we need the flowType category ? I don't think type will make much meaning of this in the runtime flow.

Did you mean flowType in flow definition or runtime context? Flow definition we still need to keep flowType.

3. We had the capability to infer the registration flow from the authentication flow. What will happen to this feature with this change ?

This was decided to be removed sometime back and currently is disabled with the config

[senthalan]

What will the be usecase for the requirement of splitting the Context for each flow? What is is the problem If we share the same context?

From the technical perspective, If we consider the runtime graph will contain the sub flows, then I don't see a technical reason to keep different context

[ThaminduDilshan]

What will the be usecase for the requirement of splitting the Context for each flow? What is is the problem If we share the same context?

Main thinking behind this design decision is to have flow type specific data. When executing different flows in runtime, some data we may have to keep scoped to a particular flow. This may not required for the current use cases, but if we consider a flow where different actors get involved (ex: workflow scenario), this may be required.

[rajithacharith]

How is the error data propergation works from the referenced flow to caller node/flow? How this handles the error properly and pass only the necessary message to the user?

[ThaminduDilshan]

Call node has a onFailure edge and it can be used to propogate errors. If not specified, referenced flow can terminate at that end. If specified, caller can decide how to handle the error.
But need to see how these error details should be cleared during return (from context or response). It has to be done conditionally. Thanks for pointing this out

[Malith-19]

Tracking: CALL nodes as a path to securing direct flow initiation

Linking some recent work that intersects with the phase-2 sub-flow direction raised here.

In #3289 (refined in #3395) we restricted direct initiation of authentication flows on POST /flow/execute: applications with the authorization_code grant type must now start authentication through GET /oauth2/authorize, not via a direct flow-execute call. We deliberately scoped that guard to AUTHENTICATION only, because registration, recovery, and user onboarding flows currently have no other way to be initiated — they must be started directly through the flow API by passing the corresponding flowType.

That leaves those three flow types as an open initiation surface on the flow API:

• REGISTRATION / RECOVERY — gated only by the per-application enable toggles; still publicly initiable when enabled.
• USER_ONBOARDING — system-wide and app-independent, with no authentication at the initiation point.

CALL nodes change this. Once a flow can transfer execution into another flow, registration and recovery no longer need to be independently initiable via flow/execute — they can be composed into the authentication journey (e.g. the "Sign up" affordance on the credentials prompt becomes a CALL into the registration flow, and the entry point remains the authentication flow that — for redirect apps — starts via /authorize). This is precisely what the sub-flow concept in the phase-2 question enables: "a flow that cannot be started directly via flow/execute and exists only to be referenced from another flow."

So beyond solving same-flow-type composition, the sub-flow concept is also the cleanest lever for shrinking the directly-initiable flow-type surface: flow types that should only ever be reached as part of a larger journey could be marked non-initiable and reachable exclusively through a CALL node from a controlled entry flow. Worth keeping this security angle in mind when deciding between the two phase-2 directions — the dedicated sub-flow concept carries this benefit that "multiple flows of the same type per application" does not.

Capturing this here so the direct-initiation hardening for registration/recovery/onboarding is tracked against the CALL-node design rather than pursued as a separate ad-hoc guard.