AppSurface Search
Section API Reference
API Reference Language: C# Component: Flow Audience: developer

Flow

Namespaces

Type

FlowDefinition<TContext>

Source

Describes a typed AppSurface Flow graph.

Type Parameters

  • TContextSerializable context type carried between flow nodes.

Remarks

A definition is immutable after construction. Nodes are identified by stable string ids so local and durable hosts can store the current node without serializing executable code. Flow ids and versions should remain stable once durable instances have been started.

Property

FlowId

string FlowId { get; } Source

Gets the stable flow identifier.

Property

Version

string Version { get; } Source

Gets the graph version.

Property

StartNodeId

string StartNodeId { get; } Source

Gets the node id where new instances start.

Property

Nodes

IReadOnlyDictionary<string, FlowNodeDescriptor<TContext>> Nodes { get; } Source

Gets all node descriptors keyed by node id.

Property

ExecutionNodes

IReadOnlyDictionary<string, FlowExecutionNode<TContext>> ExecutionNodes { get; } Source

Gets the internal execution view keyed by node id.

Remarks

The execution view is built from the copied and validated node dictionary. It preserves the public Nodes graph view while giving runners pre-resolved next-node targets.

Property

StartExecutionNode

FlowExecutionNode<TContext> StartExecutionNode { get; } Source

Gets the pre-resolved start node used by in-process runners.

Type

FlowExecutionContext<TContext>

Source

Describes one AppSurface Flow node execution.

Type Parameters

  • TContextSerializable context type carried by the flow.

Parameters

  • FlowIdStable flow id.
  • VersionFlow graph version.
  • NodeIdCurrent node id.
  • StateCurrent typed state.
  • ResumeEventOptional external event or timeout that resumed the node.

Remarks

The context is an immutable value-type snapshot so in-process runners can pass it to synchronous nodes without allocating a new reference object for every step. Runners always populate all members before invoking a node. Avoid using default instances as real execution contexts because value types can be default-created without the required flow, version, node, or state values.

Property

ActivityResult

FlowActivityWorkResult? ActivityResult { get; init; } Source

Gets the optional typed activity result that resumed the node.

Remarks

This property is null during initial execution and external-event resumption. Use the activity's FlowActivityCallsite{TWork,TResult} to validate and unwrap a result. A runner never supplies both ResumeEvent and this property for one evaluation.

Type

IFlowRunner<TContext>

Source

Runs AppSurface Flow definitions until the next external-event wait, typed activity, or terminal outcome.

Type Parameters

  • TContextSerializable context type carried by the flow.
Method

RunAsync

ValueTask<FlowRunResult<TContext>> RunAsync(FlowDefinition<TContext> definition, TContext initialContext, CancellationToken cancellationToken = default) Source

Starts a new flow instance at the definition's start node.

Parameters

  • definitionFlow definition to run.
  • initialContextInitial context.
  • cancellationTokenCancellation token.

Returns

The result after execution pauses or ends.

Method

ResumeAsync

ValueTask<FlowRunResult<TContext>> ResumeAsync(FlowDefinition<TContext> definition, string nodeId, TContext context, FlowResumeEvent resumeEvent, CancellationToken cancellationToken = default) Source

Resumes a waiting node with an external event or timeout.

Parameters

  • definitionFlow definition to run.
  • nodeIdNode id that was waiting.
  • contextPersisted context.
  • resumeEventEvent that resumed the node.
  • cancellationTokenCancellation token.

Returns

The result after execution pauses or ends.

Method

ResumeActivityAsync

ValueTask<FlowRunResult<TContext>> ResumeActivityAsync(FlowDefinition<TContext> definition, string nodeId, TContext context, FlowActivityWorkResult activityResult, CancellationToken cancellationToken = default) Source

Resumes a node that is waiting for one typed activity result.

Parameters

  • definitionFlow definition to run.
  • nodeIdNode id that requested the activity.
  • contextContext persisted with the activity request.
  • activityResultDecoded typed activity result.
  • cancellationTokenCancellation token.

Returns

The result after execution pauses or ends.

Exceptions

  • NotSupportedExceptionThrown by the default implementation when the runner has not implemented activity resumption.

Remarks

The default implementation preserves compatibility for custom v1 runners and reports that activity resumption is unsupported. Runners that surface FlowRunStatus.ActivityPending must override this method.

Type

FlowRunResult<TContext>

Source

Result returned by a flow runner after executing until the next pause or terminal outcome.

Type Parameters

  • TContextSerializable context type carried by the flow.
Method

Waiting

2 overloads
FlowRunResult<TContext> Waiting(string nodeId, string eventName, TContext context, FlowTimeout? timeout = null) Source

Creates a waiting result.

Parameters

  • nodeIdNode id where the flow paused.
  • eventNameExternal event name the node is waiting for.
  • contextContext to preserve while the flow is waiting.
  • timeoutOptional timeout associated with the wait.

Exceptions

  • ArgumentExceptionThrown when nodeId or eventName is empty.
  • ArgumentNullExceptionThrown when context is null.

Remarks

Inspect Status before reading wait-specific properties. timeout is optional and remains null for waits without a timeout.

FlowRunResult<TContext> Waiting(string nodeId, IFlowEventCallsite eventCallsite, TContext context, FlowTimeout? timeout = null) Source

Creates a waiting result with an exact typed payload contract.

Parameters

  • nodeIdNode id where the Flow paused.
  • eventCallsiteExact event name and durable payload contract.
  • contextContext to preserve while the Flow is waiting.
  • timeoutOptional timeout associated with the wait.

Returns

A waiting result that preserves immutable event metadata.

Exceptions

  • ArgumentExceptionThrown when nodeId or callsite text metadata is empty.
  • ArgumentNullExceptionThrown when eventCallsite, its payload type, or context is null.
Method

Completed

FlowRunResult<TContext> Completed(string nodeId, TContext context) Source

Creates a completed result.

Parameters

  • nodeIdNode id that completed the flow.
  • contextFinal flow context.

Exceptions

  • ArgumentExceptionThrown when nodeId is empty.
  • ArgumentNullExceptionThrown when context is null.

Remarks

A completed result does not carry wait, timeout, or fault details. Inspect Status before reading status-specific properties.

Method

TimedOut

FlowRunResult<TContext> TimedOut(string nodeId, string eventName, TContext context) Source

Creates a timed-out result.

Parameters

  • nodeIdNode id that handled the timeout branch.
  • eventNameEvent whose wait timed out.
  • contextContext after timeout handling.

Exceptions

  • ArgumentExceptionThrown when nodeId or eventName is empty.
  • ArgumentNullExceptionThrown when context is null.

Remarks

A timed-out result means timeout handling ran; it is distinct from a waiting result that carries a future timeout. Inspect Status before reading timeout-specific properties.

Method

Faulted

FlowRunResult<TContext> Faulted(string nodeId, FlowFault fault) Source

Creates a faulted result.

Parameters

  • nodeIdNode id that produced the fault.
  • faultFlow fault details.

Exceptions

  • ArgumentExceptionThrown when nodeId is empty.
  • ArgumentNullExceptionThrown when fault is null.

Remarks

Faulted results do not carry a context. Inspect Status before reading fault-specific properties.

Method

ActivityPending

FlowRunResult<TContext> ActivityPending(string nodeId, IFlowActivityRequest<TContext> activity) Source

Creates a result that pauses local execution for one typed external activity.

Parameters

  • nodeIdNode that requested the activity.
  • activityTyped activity request and context.

Returns

An activity-pending result.

Exceptions

  • ArgumentExceptionThrown when nodeId or activity metadata is empty, a contract version is invalid, or the work value does not implement its declared type.
  • ArgumentNullExceptionThrown when activity or one of its required values is null.

Remarks

The in-memory runner does not execute activities. Execute the work through a test or host boundary, construct a result with the request's typed callsite, and call IFlowRunner{TContext}.ResumeActivityAsync.

Property

Status

FlowRunStatus Status { get; } Source

Gets the runner status.

Property

Context

TContext? Context { get; } Source

Gets the latest context when the result carries one.

Property

NodeId

string? NodeId { get; } Source

Gets the node id where execution paused or ended.

Property

WaitingEventName

string? WaitingEventName { get; } Source

Gets the event name awaited by a waiting result.

Property

EventCallsite

IFlowEventCallsite? EventCallsite { get; } Source

Gets the immutable typed event contract for a waiting result, or null for a string wait.

Remarks

The runner preserves this metadata so a host can select an allowlisted payload codec. The result does not authorize, decode, or deduplicate event delivery.

Property

Timeout

FlowTimeout? Timeout { get; } Source

Gets the optional timeout associated with a waiting result.

Property

TimedOutEventName

string? TimedOutEventName { get; } Source

Gets the event whose timeout branch completed.

Property

Fault

FlowFault? Fault { get; } Source

Gets the fault details for a faulted result.

Property

Activity

IFlowActivityRequest<TContext>? Activity { get; } Source

Gets the typed activity request when Status is FlowRunStatus.ActivityPending.

Enum

FlowRunStatus

Source

Identifies the terminal or pause status returned by an AppSurface Flow runner.

Remarks

The numeric values are part of the public compatibility contract for logs, persisted state, and tests. Do not reorder, renumber, remove, or reuse values. Add new statuses only at the end with explicit numeric values and a migration/versioning plan.

Type

FlowNodeOutcome<TContext>

Source

Represents the discriminated outcome returned by a flow node.

Type Parameters

  • TContextSerializable context type carried by the flow.

Remarks

The sealed derived records form a stable discriminated-union style API that works on current C# compilers. Future native union syntax can be layered on as authoring sugar without changing the runtime contract.

Method

Next

FlowNext<TContext> Next(string nodeId, TContext context) Source

Creates an outcome that moves execution to another declared node.

Parameters

  • nodeIdTarget node id.
  • contextContext to pass to the target node.

Returns

A next-node outcome.

Method

Wait

2 overloads
FlowWait<TContext> Wait(string eventName, TContext context, FlowTimeout? timeout = null) Source

Creates an outcome that waits for an external event before executing this node again.

Parameters

  • eventNameExternal event name.
  • contextContext to persist while waiting.
  • timeoutOptional wait timeout.

Returns

A wait outcome.

FlowWait<TContext> Wait<TPayload>(FlowEventCallsite<TPayload> callsite, TContext context, FlowTimeout? timeout = null) Source

Creates an outcome that waits for an external event carrying one exact typed payload contract.

Type Parameters

  • TPayloadExpected allowlisted event payload type.

Parameters

  • callsiteStable event name and durable payload contract.
  • contextContext to persist while waiting.
  • timeoutOptional wait timeout.

Returns

A typed external-event wait outcome.

Exceptions

  • ArgumentNullExceptionThrown when callsite or context is null.
Method

TimedOut

FlowTimedOut<TContext> TimedOut(string eventName, TContext context) Source

Creates an outcome indicating the node handled a timeout branch.

Parameters

  • eventNameEvent whose wait expired.
  • contextContext after timeout handling.

Returns

A timed-out outcome.

Method

Complete

FlowComplete<TContext> Complete(TContext context) Source

Creates a successful completion outcome.

Parameters

  • contextFinal context.

Returns

A completion outcome.

Method

Fault

FlowFaultOutcome<TContext> Fault(string code, string message) Source

Creates a fault outcome.

Parameters

  • codeStable machine-readable code.
  • messageHuman-readable diagnostic message.

Returns

A fault outcome.

Method

Activity

FlowActivity<TContext, TWork, TResult> Activity<TWork, TResult>(FlowActivityCallsite<TWork, TResult> callsite, TWork work, TContext context) Source

Creates an outcome that schedules one typed external activity and pauses the Flow node for its result.

Type Parameters

  • TWorkSerializable work contract sent to the activity executor.
  • TResultSerializable result contract returned to the same node.

Parameters

  • callsiteStable typed activity callsite.
  • workWork value to persist and execute.
  • contextContext to persist atomically with the activity command.

Returns

An activity outcome.

Exceptions

  • ArgumentNullExceptionThrown when callsite, work, or context is null.

Remarks

Returning this outcome does not execute work. A durable host records the transition and activity command atomically, executes the work through its provider-safe worker boundary, and resumes this same node with FlowActivityWorkResult{TResult}. Nodes must not perform the external effect themselves.

Type

FlowNext<TContext>

Source

Moves execution to another node in the same flow definition.

Type Parameters

  • TContextSerializable context type carried by the flow.
Property

NodeId

string NodeId { get; } Source

Gets the target node id.

Property

Context

TContext Context { get; } Source

Gets the context to pass to the target node.

Type

FlowWait<TContext>

Source

Pauses execution until a named external event or timeout is delivered by the host.

Type Parameters

  • TContextSerializable context type carried by the flow.
Property

EventName

string EventName { get; } Source

Gets the external event name.

Property

EventCallsite

IFlowEventCallsite? EventCallsite { get; } Source

Gets the exact typed event contract, or null when this wait explicitly accepts no payload.

Property

Context

TContext Context { get; } Source

Gets the context to persist while waiting.

Property

Timeout

FlowTimeout? Timeout { get; } Source

Gets the optional wait timeout.

Type

FlowTimedOut<TContext>

Source

Reports that a timeout branch has been handled by a node.

Type Parameters

  • TContextSerializable context type carried by the flow.
Property

EventName

string EventName { get; } Source

Gets the event whose wait expired.

Property

Context

TContext Context { get; } Source

Gets the context after timeout handling.

Type

FlowComplete<TContext>

Source

Completes a flow instance successfully.

Type Parameters

  • TContextSerializable context type carried by the flow.
Property

Context

TContext Context { get; } Source

Gets the final context.

Type

FlowFaultOutcome<TContext>

Source

Fails a flow instance with a process-level fault.

Type Parameters

  • TContextSerializable context type carried by the flow.
Property

Fault

FlowFault Fault { get; } Source

Gets the fault details.

Remarks

This member intentionally hides the static fault factory on FlowNodeOutcome{TContext}.

Type

FlowActivity<TContext, TWork, TResult>

Source

Schedules one typed external activity and pauses the current Flow node until its result is available.

Type Parameters

  • TContextSerializable context type carried by the Flow.
  • TWorkSerializable work contract sent to the activity executor.
  • TResultSerializable result contract returned to the same node.

Remarks

The generic properties are convenient for node tests. Durable hosts should consume IFlowActivityRequest{TContext} to read declared CLR types, versions, work, and context without reflection.

Property

Callsite

FlowActivityCallsite<TWork, TResult> Callsite { get; } Source

Gets the stable typed callsite.

Property

Work

TWork Work { get; } Source

Gets the typed work value.

Property

Context

TContext Context { get; } Source

Gets the Flow context to persist atomically with the activity command.

Type

AppSurfaceFlowModule

Source

Registers the AppSurface Flow core services.

Remarks

The module is passive: it adds the one-node transition evaluator, in-memory runner, definition registry, and options used by local tests and host-specific adapters. It does not start background workers, create storage, schedule timers, execute activities, or replace AppSurface startup composition.

Type

FlowFault

Source

Describes a fault returned by a flow node or adapter.

Remarks

Faults are flow results, not exceptions. Use them for expected process failures that should be visible to callers or durable orchestration logs. Use exceptions for invalid definitions, host configuration errors, and programmer bugs.

Property

Code

string Code { get; } Source

Gets the stable machine-readable code.

Property

Message

string Message { get; } Source

Gets the human-readable diagnostic message.

Type

FlowAuthoringAttribute

Source

Marks a partial type as the generated authoring specification for an AppSurface Flow.

Remarks

Use generated authoring when a flow should be declared as typed transformer nodes with compile-time validation of outcome coverage. Use FlowGraphBuilder{TContext} directly when a host needs dynamic graph construction, low-level runtime control, or compatibility with hand-authored nodes. The annotated type must be a non-generic partial class. Record and nested generated flow specifications are not supported. Generated authoring is additive: the generator lowers the annotated specification into the existing FlowDefinition{TContext} runtime contract without changing low-level flow APIs. Avoid mixing generated definition helpers with manual low-level node registration for the same flow because that makes mapping ownership unclear.

Property

FlowId

string FlowId { get; } Source

Gets the stable flow identifier used by generated definitions.

Property

Version

string Version { get; set; } Source

Gets or sets the stable graph version. Defaults to 1.

Type

FlowNodeAttribute

Source

Marks a partial nested type as a generated-authoring flow node.

Remarks

Apply this attribute to a partial class nested inside a FlowAuthoringAttribute flow type. The node class must implement IFlowTransformerNode{TInput,TOutcome} where TInput matches InputContextType and TOutcome is the generated outcome union for that node.

Property

NodeId

string NodeId { get; } Source

Gets the stable node identifier.

Property

InputContextType

Type InputContextType { get; } Source

Gets the context type consumed by the node.

Type

FlowStartAttribute

Source

Marks one generated-authoring node as the flow start node.

Remarks

Exactly one node per generated flow must be marked with FlowStartAttribute. If a flow declares zero or multiple start nodes, the generator reports diagnostic ASFLOWA004 and does not produce the generated definition helpers for that invalid flow.

Type

FlowOutcomeAttribute

Source

Declares one generated outcome case a transformer node can return.

Remarks

Outcome contexts are nominal ports used by the generated graph validator. FlowOutcomeKind.Next must carry the input context type of exactly one target node. FlowOutcomeKind.Wait and FlowOutcomeKind.TimedOut resume the current node, so they must carry that node's input context type. FlowOutcomeKind.Fault must carry FlowFault. FlowOutcomeKind.Complete is terminal and does not require a target node. FlowOutcomeKind.Activity uses the five-argument constructor to declare work and result contracts, and its output context must match the current node input context.

Property

Name

string Name { get; } Source

Gets the stable outcome name.

Property

Kind

FlowOutcomeKind Kind { get; } Source

Gets the outcome kind.

Property

OutputContextType

Type OutputContextType { get; } Source

Gets the context type carried by this outcome.

Property

WorkType

Type? WorkType { get; } Source

Gets the activity work contract type, when this is an FlowOutcomeKind.Activity declaration.

Property

ResultType

Type? ResultType { get; } Source

Gets the activity result contract type, when this is an FlowOutcomeKind.Activity declaration.

Property

CallsiteId

string? CallsiteId { get; set; } Source

Gets or sets an explicit stable activity callsite id.

Remarks

When omitted, generated authoring uses <node-id>.<outcome-name>. Either form is a durable identifier within a Flow definition and must not change while nonterminal instances reference it.

Property

WorkContractVersion

int WorkContractVersion { get; set; } Source

Gets or sets the positive serialized activity work contract version. Defaults to one.

Property

ResultContractVersion

int ResultContractVersion { get; set; } Source

Gets or sets the positive serialized activity result contract version. Defaults to one.

Type

FlowGraphMappingAttribute

Source

Describes one generated graph mapping method for analyzer validation.

Remarks

Do not apply this attribute manually. The generator emits it on generated GraphBuilder mapping methods so analyzers can validate explicit BuildDefinition lambda coverage. Manually applying it can make graph coverage diagnostics misleading. This attribute is emitted by generated authoring code. Application code should use FlowOutcomeAttribute to declare outcomes instead of applying this attribute manually.

Property

NodeId

string NodeId { get; } Source

Gets the stable source node identifier.

Property

OutcomeName

string OutcomeName { get; } Source

Gets the stable outcome name.

Property

OutputContextType

Type OutputContextType { get; } Source

Gets the context type carried by this outcome.

Type

IFlowTransformerNode<TInput, TOutcome>

Source

Executes one generated-authoring transformer node.

Type Parameters

  • TInputTyped input context consumed by the node.
  • TOutcomeGenerated outcome union type returned by the node.

Remarks

Implementations receive a FlowTransformerContext{TInput} and must return a non-null generated outcome case. The generated adapter lowers that case into the v1 runtime contract and the runner enforces the non-null outcome requirement. Exceptions thrown by an implementation propagate to the caller; use FlowOutcomeKind.Fault with FlowFault for expected process failures that should be represented as flow results. Nodes should honor cancellation and must not perform externally visible side effects; return FlowOutcomeKind.Activity so a durable host can commit the command before executing work. A node may be evaluated more than once when a process dies before the returned transition commits.

Method

ExecuteAsync

ValueTask<TOutcome> ExecuteAsync(FlowTransformerContext<TInput> context, CancellationToken cancellationToken = default) Source

Executes the node and returns a generated outcome case.

Parameters

  • contextTyped authoring execution context.
  • cancellationTokenCancellation token supplied by the runner. The default value is provided for manual invocation convenience.

Returns

A generated outcome case.

Type

FlowTransformerContext<TInput>

Source

Describes one generated-authoring transformer execution.

Type Parameters

  • TInputTyped input context consumed by the node.

Parameters

  • FlowIdStable flow id.
  • VersionFlow graph version.
  • NodeIdCurrent node id.
  • StateTyped input state.
  • ResumeEventOptional external event or timeout that resumed the node.

Remarks

FlowId, Version, and NodeId identify the current definition and node being executed. State is the typed input context unwrapped from the generated envelope; the record does not validate it, and generated adapters assume it is non-null. ResumeEvent is null for initial execution and non-null when a node resumes after an external event or timeout. ActivityResult is non-null only when a typed activity resumes the node; runners never populate both resume forms at once.

Property

ActivityResult

FlowActivityWorkResult? ActivityResult { get; init; } Source

Gets the optional typed activity result that resumed this transformer node.

Remarks

Use the generated outcome callsite's TryGetResult or GetResult method instead of casting FlowActivityWorkResult.Result. The property is null on initial and external-event execution.

Enum

FlowOutcomeKind

Source

Runtime outcome kinds supported by generated AppSurface Flow authoring.

Remarks

The numeric values are part of the public compatibility contract. Do not renumber or reorder existing values.

Type

FlowTransitionFaultCodes

Source

Stable fault codes shared by the built-in transition evaluator and runners that translate its decisions.

Type

FlowTransitionInput<TContext>

Source

Input for one host-neutral Flow node evaluation.

Type Parameters

  • TContextSerializable context type carried by the Flow.
Property

NodeId

string NodeId { get; } Source

Gets the current node id.

Property

Context

TContext Context { get; } Source

Gets the current Flow context.

Property

ResumeEvent

FlowResumeEvent? ResumeEvent { get; } Source

Gets the optional external event or timeout that resumed the node.

Property

ActivityResult

FlowActivityWorkResult? ActivityResult { get; } Source

Gets the optional typed activity result that resumed the node.

Type

FlowTransition<TContext>

Source

Host-neutral decision produced by evaluating exactly one Flow node.

Type Parameters

  • TContextSerializable context type carried by the Flow.

Remarks

Inspect Kind before reading kind-specific properties. A durable host commits this decision before evaluating another node. It must atomically persist an FlowTransitionKind.Activity decision, its activity command, and the waiting context.

Method

Next

FlowTransition<TContext> Next(string nodeId, string nextNodeId, TContext context) Source

Creates a next-node transition carrying the declared target and persisted context.

Parameters

  • nodeIdNode that produced the transition.
  • nextNodeIdDeclared target node.
  • contextContext to persist for the target node.

Returns

A transition whose target and context are populated.

Method

Waiting

FlowTransition<TContext> Waiting(string nodeId, string eventName, IFlowEventCallsite? eventCallsite, TContext context, FlowTimeout? timeout) Source

Creates a wait transition carrying the event contract, persisted context, and optional timeout.

Parameters

  • nodeIdNode that produced the transition.
  • eventNameExternal event name.
  • eventCallsiteExact typed event contract, or null for an explicit no-payload wait.
  • contextContext to persist while waiting.
  • timeoutOptional durable timeout.

Returns

A transition whose event, context, and timeout fields are populated.

Method

TimedOut

FlowTransition<TContext> TimedOut(string nodeId, string eventName, TContext context) Source

Creates a timeout transition carrying the expired event name and resulting context.

Parameters

  • nodeIdNode that handled the timeout.
  • eventNameExternal event whose wait expired.
  • contextContext after timeout handling.

Returns

A transition whose event name and context are populated.

Method

Completed

FlowTransition<TContext> Completed(string nodeId, TContext context) Source

Creates a terminal completion transition carrying the final context.

Parameters

  • nodeIdNode that completed the Flow.
  • contextFinal context.

Returns

A transition whose context is populated.

Method

Faulted

FlowTransition<TContext> Faulted(string nodeId, FlowFault fault) Source

Creates a fault transition carrying only the process-level fault.

Parameters

  • nodeIdNode associated with the fault.
  • faultStable fault code and safe message.

Returns

A transition whose fault is populated and whose context is absent.

Method

ActivityRequested

FlowTransition<TContext> ActivityRequested(string nodeId, IFlowActivityRequest<TContext> activity) Source

Creates an activity transition carrying the activity request and its persisted context.

Parameters

  • nodeIdNode that requested the activity.
  • activityTyped activity request produced by the node.

Returns

A transition whose activity and context are populated.

Property

Kind

FlowTransitionKind Kind { get; } Source

Gets the transition kind.

Property

NodeId

string NodeId { get; } Source

Gets the node that produced the transition.

Property

Context

TContext? Context { get; } Source

Gets the context carried by non-fault transitions.

Property

NextNodeId

string? NextNodeId { get; } Source

Gets the declared target for a FlowTransitionKind.Next transition.

Property

EventName

string? EventName { get; } Source

Gets the event name carried by wait and timeout transitions.

Property

EventCallsite

IFlowEventCallsite? EventCallsite { get; } Source

Gets the exact typed event contract for a wait, or null for an explicit no-payload wait.

Property

Timeout

FlowTimeout? Timeout { get; } Source

Gets the optional timeout carried by a wait transition.

Property

Fault

FlowFault? Fault { get; } Source

Gets the process-level fault carried by a fault transition.

Property

Activity

IFlowActivityRequest<TContext>? Activity { get; } Source

Gets the typed request metadata carried by an activity transition.

Type

IFlowTransitionEvaluator<TContext>

Source

Evaluates exactly one Flow node and maps its outcome to a host-neutral transition.

Type Parameters

  • TContextSerializable context type carried by the Flow.

Remarks

This is the shared semantic boundary for in-memory, Durable Task, and PostgreSQL hosts. It does not loop through FlowNext{TContext} transitions, persist state, validate serialization, schedule timers, or execute activities. Nodes can be evaluated again when a process dies before the host commits the returned transition, so they must be side-effect-free and must receive nondeterministic inputs through explicit context or resume contracts. Transition creation is package-owned so every runner observes the same mapping and validation semantics. External implementations should decorate and delegate to FlowTransitionEvaluator{TContext} for concerns such as telemetry; they cannot manufacture alternative transitions. Express custom process behavior through node outcomes instead of replacing the evaluator's transition semantics.

Method

EvaluateAsync

ValueTask<FlowTransition<TContext>> EvaluateAsync(FlowDefinition<TContext> definition, FlowTransitionInput<TContext> input, CancellationToken cancellationToken = default) Source

Evaluates one declared node.

Parameters

  • definitionImmutable Flow definition containing the node.
  • inputNode id, context, and optional resume input.
  • cancellationTokenToken that cancels node execution.

Returns

One mapped transition. Missing nodes, undeclared next targets, and unsupported outcomes become fault transitions; caller argument errors, cancellation, and node exceptions propagate.

Exceptions

  • ArgumentNullExceptionThrown when definition or input is null, or when the selected node returns a null outcome.
  • OperationCanceledExceptionThrown when cancellationToken is canceled before or during node execution.
Property

EvaluatorId

string EvaluatorId { get; } Source

Gets the stable, host-independent evaluator identity used by durable execution manifests.

Property

EvaluatorVersion

string EvaluatorVersion { get; } Source

Gets the evaluator semantics version used by durable execution manifests.

Type

FlowTransitionEvaluator<TContext>

Source

Default host-neutral implementation of IFlowTransitionEvaluator{TContext}.

Type Parameters

  • TContextSerializable context type carried by the Flow.
Enum

FlowTransitionKind

Source

Identifies the host-neutral decision produced by evaluating exactly one Flow node.

Remarks

Numeric values are a compatibility contract for durable hosts and telemetry. Do not reorder, renumber, remove, or reuse values. Append new transition kinds with explicit numeric values.

Type

FlowTimeout

Source

Describes a timeout requested by a flow wait outcome.

Remarks

The core in-memory runner returns timeout metadata to callers; durable hosts are responsible for turning it into a durable timer and racing that timer against the external event.

Property

Duration

TimeSpan Duration { get; } Source

Gets the timeout duration.

Type

FlowNodeDescriptor<TContext>

Source

Describes one node in a flow definition.

Type Parameters

  • TContextSerializable context type carried by the flow.
Property

NodeId

string NodeId { get; } Source

Gets the stable node id.

Property

Node

IFlowNode<TContext> Node { get; } Source

Gets the executable node implementation.

Property

NextNodeIds

IReadOnlySet<string> NextNodeIds { get; } Source

Gets the allowed next-node targets.

Type

FlowGraphBuilder<TContext>

Source

Builds and validates typed AppSurface Flow graphs.

Type Parameters

  • TContextSerializable context type carried by the flow.

Remarks

The builder validates declared transitions before returning a definition. Every target passed to AddNode(string, IFlowNode{TContext}, string[]) must exist in the final graph. Cycles are allowed because long-running business processes often revisit a review, remediation, or wait step.

Method

Create

FlowGraphBuilder<TContext> Create(string flowId, string version = "1") Source

Creates a new builder.

Parameters

  • flowIdStable flow id.
  • versionFlow graph version. Defaults to 1.

Returns

A new builder instance.

Method

AddNode

FlowGraphBuilder<TContext> AddNode(string nodeId, IFlowNode<TContext> node, params string[] nextNodeIds) Source

Adds a node and declares the node ids it may return from a FlowNext{TContext} outcome.

Parameters

  • nodeIdStable node id.
  • nodeNode implementation.
  • nextNodeIdsAllowed FlowNext{TContext}.NodeId targets.

Returns

The current builder.

Exceptions

  • ArgumentExceptionThrown when the id is empty or duplicated.
Method

StartAt

FlowGraphBuilder<TContext> StartAt(string nodeId) Source

Sets the node id used for new flow instances.

Parameters

  • nodeIdStart node id.

Returns

The current builder.

Method

Build

FlowDefinition<TContext> Build() Source

Validates and creates an immutable flow definition.

Returns

The validated definition.

Exceptions

  • FlowDefinitionExceptionThrown when the graph is incomplete or references missing nodes.
Type

AppSurfaceFlowOptions

Source

Configures local AppSurface Flow execution behavior.

Remarks

These options affect the in-memory runner only. Durable hosts should keep replay, persistence, external events, and timer policy in their durable orchestration layer and use this package's contracts for typed graph behavior.

Property

MaxStepsPerRun

int MaxStepsPerRun { get; set; } Source

Gets or sets the maximum number of synchronous node transitions allowed during one in-memory run.

Remarks

The default value, 1000, protects local tests and examples from accidental infinite loops. Set a higher value for intentionally dense local workflows. Values less than 1 are treated as configuration errors when a runner starts.

Type

InMemoryFlowRunner<TContext>

Source

Runs AppSurface Flow definitions in memory for local development and tests.

Type Parameters

  • TContextSerializable context type carried by the flow.

Remarks

This runner does not persist state, create durable timers, or buffer external events. It executes synchronously through FlowNext{TContext} outcomes and stops at FlowWait{TContext}, FlowActivity{TContext,TWork,TResult}, FlowComplete{TContext}, FlowTimedOut{TContext}, or FlowFaultOutcome{TContext}. It reports activities to the caller; it never executes external work itself.

Type

IFlowEventCallsite

Source

Describes a typed external-event wait without exposing CLR type names to durable storage.

Remarks

This interface describes manifest metadata only. A durable host validates an authorized event against its persisted wait registration, selects an allowlisted codec through ContractName and ContractVersion, validates the decoded value against PayloadType, and only then invokes the Flow evaluator. The evaluator does not authorize, decode, or deduplicate external events.

Property

EventName

string EventName { get; } Source

Gets the exact case-sensitive event name.

Property

PayloadType

Type PayloadType { get; } Source

Gets the expected event payload CLR type for allowlisted codec lookup.

Property

ContractName

string ContractName { get; } Source

Gets the exact durable payload contract name.

Property

ContractVersion

string ContractVersion { get; } Source

Gets the exact durable payload contract version.

Type

FlowEventCallsite<TPayload>

Source

Declares the exact typed payload contract accepted by one external Flow event wait.

Type Parameters

  • TPayloadAllowlisted event payload type.

Remarks

The event name and contract identity are durable manifest values. Change them only with a new Flow definition version. Values are preserved exactly and compared ordinally by durable hosts; there is no trimming, case folding, or normalization. TPayload is runtime codec metadata rather than a durable wire identifier. Use the string-based Wait overload when an event intentionally carries no payload.

Type

FlowEventCallsiteContract

Source

Validates and snapshots event-callsite metadata at public host boundaries.

Remarks

IFlowEventCallsite is extensible, so implementations can expose mutable or inconsistent getters. Capturing each value once prevents later mutation from changing an already-created wait or durable decision.

Method

Snapshot

IFlowEventCallsite Snapshot(IFlowEventCallsite eventCallsite, string parameterName) Source

Creates an immutable, validated copy of an event callsite.

Parameters

  • eventCallsiteCallsite supplied through a public API.
  • parameterNamePublic parameter name used by validation exceptions.

Returns

Immutable event metadata safe to retain.

Type

IFlowNode<TContext>

Source

Executes one typed step in an AppSurface Flow graph.

Type Parameters

  • TContextSerializable context type carried by the flow.

Remarks

Nodes should be deterministic, idempotent where practical, and explicit about process outcomes. Durable hosts may replay orchestration decisions around node execution, so avoid hidden global side effects in nodes and keep external I/O behind durable activity boundaries.

Method

ExecuteAsync

ValueTask<FlowNodeOutcome<TContext>> ExecuteAsync(FlowExecutionContext<TContext> context, CancellationToken cancellationToken = default) Source

Executes the node.

Parameters

  • contextExecution context for the current node.
  • cancellationTokenCancellation token supplied by the runner.

Returns

A discriminated outcome that tells the runner how to continue.

Type

FlowExecutionNode<TContext>

Source

Internal, prevalidated node view used by runners to avoid repeated graph-routing lookups.

Type Parameters

  • TContextSerializable context type carried by the flow.

Remarks

Instances are created only by FlowDefinition{TContext} after the public node dictionary has been copied and validated. The public API remains FlowDefinition{TContext}.Nodes; this type exists only to keep execution routing internal and fail-closed.

Method

SetNextNodes

void SetNextNodes(IReadOnlyDictionary<string, FlowExecutionNode<TContext>> nextNodes) Source

Assigns the prevalidated next-node map once all execution nodes have been created.

Parameters

  • nextNodesResolved next-node targets.
Property

Descriptor

FlowNodeDescriptor<TContext> Descriptor { get; } Source

Gets the public descriptor executed for this node.

Property

NextNodes

IReadOnlyDictionary<string, FlowExecutionNode<TContext>> NextNodes { get; set; } Source

Gets the prevalidated next-node targets keyed by allowed target id.

Type

IFlowDefinitionRegistry

Source

Stores AppSurface Flow definitions by context type, flow id, and version.

Method

Register

void Register<TContext>(FlowDefinition<TContext> definition) Source

Registers a flow definition.

Type Parameters

  • TContextContext type for the definition.

Parameters

  • definitionDefinition to register.

Exceptions

  • ArgumentExceptionThrown when the same context, flow id, and version are already registered.
Method

TryGet

bool TryGet<TContext>(string flowId, string version, out FlowDefinition<TContext>? definition) Source

Tries to resolve a registered flow definition.

Type Parameters

  • TContextExpected context type.

Parameters

  • flowIdFlow id.
  • versionFlow version.
  • definitionResolved definition, when found.

Returns

true when a matching definition exists.

Method

GetRequired

FlowDefinition<TContext> GetRequired<TContext>(string flowId, string version) Source

Resolves a registered flow definition or throws a diagnostic exception.

Type Parameters

  • TContextExpected context type.

Parameters

  • flowIdFlow id.
  • versionFlow version.

Returns

The matching definition.

Exceptions

  • FlowDefinitionExceptionThrown when the definition is missing or registered with another context type.
Type

FlowDefinitionRegistry

Source

Thread-safe in-memory implementation of IFlowDefinitionRegistry.

Type

FlowActivityCallsite<TWork, TResult>

Source

Describes a typed, stable activity callsite in a Flow definition.

Type Parameters

  • TWorkSerializable work contract sent to the activity executor.
  • TResultSerializable result contract returned to the waiting Flow node.

Remarks

A callsite id and its contract versions are durable identifiers. Do not change them while nonterminal Flow instances can reference the callsite. Expected business failures belong in TResult; exhausted technical failures and ambiguous provider outcomes are host-level suspension concerns.

Method

CreateResult

FlowActivityWorkResult<TResult> CreateResult(TResult result) Source

Creates the typed result used to resume this callsite's Flow node.

Parameters

  • resultDecoded activity result.

Returns

A result carrying this callsite's identity and result contract version.

Exceptions

  • ArgumentNullExceptionThrown when result is null.
Method

TryGetResult

bool TryGetResult(FlowActivityWorkResult? workResult, out TResult result) Source

Attempts to read a resumed activity result for this exact callsite and result contract.

Parameters

  • workResultActivity result supplied by the host, or null for initial node evaluation.
  • resultThe typed result when the identity and contract match.

Returns

true when the result belongs to this callsite; otherwise, false.

Remarks

A mismatched result is not coerced. Durable hosts should normally prevent mismatches by validating the persisted wait registration before evaluating the node. Nodes can use this method to distinguish initial execution from activity resumption without casting or reflection.

Method

GetResult

TResult GetResult(FlowActivityWorkResult? workResult) Source

Reads a resumed activity result for this exact callsite and result contract.

Parameters

  • workResultActivity result supplied by the host.

Returns

The typed activity result.

Exceptions

  • FlowDefinitionExceptionThrown when the result is absent or belongs to a different callsite, CLR type, or contract version.
Property

CallsiteId

string CallsiteId { get; } Source

Gets the stable callsite identifier.

Property

WorkContractVersion

int WorkContractVersion { get; } Source

Gets the serialized work contract version.

Property

ResultContractVersion

int ResultContractVersion { get; } Source

Gets the serialized result contract version.

Type

IFlowActivityRequest<TContext>

Source

Provides non-generic activity request metadata to durable Flow hosts.

Type Parameters

  • TContextSerializable context persisted while the activity runs.

Remarks

The metadata is intentionally exposed without reflection so a host can select registered codecs from the declared CLR types and contract versions. The interface does not authorize execution or serialize values itself.

Method

CreateResult

FlowActivityWorkResult CreateResult(object result) Source

Wraps a decoded result in this request's typed callsite contract.

Parameters

  • resultDecoded result whose runtime value must implement ResultType.

Returns

A typed work result suitable for resuming the Flow node.

Exceptions

  • ArgumentNullExceptionThrown when result is null.
  • ArgumentExceptionThrown when result has the wrong CLR type.
  • InvalidOperationExceptionThrown by validated host-boundary wrappers when an extensible implementation returns null, substitutes a different decoded value, or returns callsite, type, or version metadata that differs from the captured request.

Remarks

This method lets a host bridge a registered non-generic codec back into the typed Flow result without reflection. Implementations must wrap the exact decoded value supplied by the host and preserve the request's callsite id, declared result type, and result contract version.

Property

CallsiteId

string CallsiteId { get; } Source

Gets the stable callsite identifier.

Property

WorkType

Type WorkType { get; } Source

Gets the declared work CLR type.

Property

WorkContractVersion

int WorkContractVersion { get; } Source

Gets the serialized work contract version.

Property

ResultType

Type ResultType { get; } Source

Gets the declared result CLR type.

Property

ResultContractVersion

int ResultContractVersion { get; } Source

Gets the serialized result contract version.

Property

Work

object Work { get; } Source

Gets the typed work value through a non-generic host boundary.

Property

Context

TContext Context { get; } Source

Gets the Flow context to persist atomically with the activity command.

Type

FlowActivityRequestContract

Source

Validates and snapshots activity requests supplied through extensible public host boundaries.

Remarks

A request snapshot preserves the metadata, work value, and context that a host must persist atomically. The work and context contracts themselves should be immutable or serialized immediately; this helper does not deep-clone application values.

Method

Snapshot

IFlowActivityRequest<TContext> Snapshot<TContext>(IFlowActivityRequest<TContext> activity, string parameterName) Source

Creates an immutable, validated activity-request wrapper.

Type Parameters

  • TContextSerializable Flow context type.

Parameters

  • activityRequest supplied through a public API.
  • parameterNamePublic parameter name used by validation exceptions.

Returns

A request whose metadata cannot change after validation.

Type

FlowActivityWorkResult

Source

Base contract for a decoded activity result supplied when a waiting node resumes.

Remarks

Results contain safe application contracts, not provider response bodies or credentials. Durable hosts validate the callsite, CLR type, and result contract version against the persisted activity wait before node evaluation.

Property

CallsiteId

string CallsiteId { get; } Source

Gets the activity callsite that produced the result.

Property

ResultType

Type ResultType { get; } Source

Gets the declared result CLR type.

Property

ResultContractVersion

int ResultContractVersion { get; } Source

Gets the serialized result contract version.

Property

Result

object Result { get; } Source

Gets the decoded result through a non-generic host boundary.

Type

FlowActivityWorkResult<TResult>

Source

Carries a decoded, typed activity result for node resumption.

Type Parameters

  • TResultSerializable result contract returned by the activity executor.
Property

Value

TResult Value { get; } Source

Gets the typed decoded result.

Type

FlowDefinitionException

Source

Represents an invalid flow definition or an attempt to execute a node transition that the definition does not allow.

Remarks

Definition errors are deterministic authoring mistakes. They are surfaced as exceptions so tests and startup validation fail loudly before a durable instance is started.

Type

FlowResumeEvent

Source

Describes an external event or timeout that resumed a waiting flow node.

Method

Timeout

FlowResumeEvent Timeout(string eventName) Source

Creates a timeout resume event for the supplied wait event.

Parameters

  • eventNameWait event whose timeout expired.

Returns

A timeout resume event.

Property

EventName

string EventName { get; } Source

Gets the event name.

Property

Payload

object? Payload { get; } Source

Gets the optional event payload.

Property

IsTimeout

bool IsTimeout { get; } Source

Gets a value indicating whether this event represents a timeout.