Documentation / Reference

Workflow definition reference

JSON and YAML use the same definition. Start with a runtime group and phases; expand an option group when you need it.

Choose where work runs

Option	Behavior
default_group / group	Select an installed runtime group; a phase group overrides the workflow default.
async_sqs	Queue work on the group's managed SQS queue; the runner reports completion later.
sync_lambda	Invoke the group's runner Lambda and wait for its response.
type: async_tool	Separate external-operation contract: dispatch, durable wait and authenticated callback.

The operator installs queues and runners once. Workflow authors use group names. Application CDK publishes handler artifacts; it does not install the execution engine.

Minimal example · JSON / YAML

JSON

json

{
  "name": "hello-docs",
  "version": "1.0.0",
  "default_group": "python-standard",
  "phases": {
    "start": {
      "requires": [],
      "service": "hello",
      "scope": "root",
      "mode": "sync_lambda"
    },
    "finish": {
      "requires": [
        "start"
      ],
      "service": "hello",
      "scope": "fan_in_all",
      "terminal": true,
      "mode": "sync_lambda"
    }
  }
}

YAML

yaml

name: hello-docs
version: 1.0.0
default_group: python-standard
phases:
  start:
    requires: []
    service: hello
    scope: root
    mode: sync_lambda
  finish:
    requires:
      - start
    service: hello
    scope: fan_in_all
    terminal: true
    mode: sync_lambda

All definition options

127 fields across 17 objects, checked against pinned main. Publication pins are generated metadata. Memory override fields are recognized only to reject them; choose a runtime group instead.

Workflow

Option / type	Meaning	When omitted
`name` String	Human-readable workflow name.	Empty string
`version` String	Workflow version; string or integer accepted.	1.0.0
`controls` Option<crate::controls::WorkflowControlPolicy>	Optional workflow-level execution controls, budgets, gates, and policy hooks (RF-CONTROL-01 Part C).	Omitted (inherits or disables this setting)
`deployment_id` Option<String> Aliases: deploymentId	Optional immutable published deployment identifier (`DeploymentManifest.deployment_id`).	Omitted (inherits or disables this setting)
`default_group` Option<String> Aliases: defaultGroup, runtimeGroup	Optional default Runtime Group ID (`"rust-light"`, `"node-standard"`, `"python-heavy"`, etc.) inherited by any phase that does not declare its own `group` override.	Omitted (inherits or disables this setting)
`default_role` Option<String> Aliases: defaultRole	Optional default approved IAM role ARN or alias inherited by any phase that does not declare its own `role`.	Omitted (inherits or disables this setting)
`memory_override_mb` Option<Value> Aliases: memoryMb, memory_mb, lambdaMemory, lambda_memory, workerMemoryMib	Captures any forbidden workflow-level Lambda memory override (`memoryMb`, `lambdaMemory`) so validation rejects it.	Omitted (inherits or disables this setting)
`coordination` Option<CoordinationConfig>	Optional workflow-level Valkey coordination retention configuration (`defaultTtl: "15m"`).	Omitted (inherits or disables this setting)
`defaults` Option<WorkflowDefaults>	Optional workflow-level defaults (`phaseTimeout: "5m"`).	Omitted (inherits or disables this setting)
`lanes` HashMap<String, LaneDef>	Advanced named bindings to existing SQS queues or Lambda functions; normal workflows use runtime groups.	Empty
`phases` HashMap<String, PhaseDef>	Phase map keyed by ID, or an array with an id on every phase.	Empty

Phase

Option / type	Meaning	When omitted
`id` Option<String>	Optional phase identifier when deserialized from a YAML/JSON sequence (`phases: [{ id: extract, ... }]`).	Omitted (inherits or disables this setting)
`requires` Vec<String>	Upstream phase IDs that must complete before this phase runs. Empty means an entry phase.	Empty
`service` String Aliases: handler	Logical handler or service identifier passed to the client runner layer.	Empty string
`inputs` Value	Application input passed to this handler.	null
`lambda` Option<String>	Legacy execution role hint (`"runner"`, `"qa"`, `"orchestrator"`, `"export"`).	Omitted (inherits or disables this setting)
`lane` Option<String>	Logical lane name referencing `WorkflowDef::lanes` (or a direct queue URL / ARN).	Omitted (inherits or disables this setting)
`group` Option<String> Aliases: runtimeGroup, runtime_group	Explicit Runtime Group identifier for this phase (e.g. `"rust-light"`, `"node-standard"`, `"python-heavy"`, `"java-standard"`, or a custom group ID). Overrides `WorkflowDef::default_group` when present and routes the phase directly to that group's SQS queue and Runner Lambda.	Omitted (inherits or disables this setting)
`pinned_group_version` Option<u32> Aliases: pinnedGroupVersion	Pinned Runtime Group `config_version` captured when the workflow version was admitted/published (RF-MEM-01 Part F).	Omitted (inherits or disables this setting)
`pinned_worker_memory_mib` Option<u32> Aliases: pinnedWorkerMemoryMib	Pinned worker memory in MiB captured when the workflow version was admitted/published (RF-MEM-01 Part F).	Omitted (inherits or disables this setting)
`pinned_handler_slice_limit_mib` Option<u32> Aliases: pinnedHandlerSliceLimitMib	Pinned subprocess handler memory slice limit in MiB captured when the workflow version was admitted/published (RF-MEM-01 Part F).	Omitted (inherits or disables this setting)
`pinned_group_timeout_secs` Option<u32> Aliases: pinnedGroupTimeoutSecs	Pinned runtime group timeout in seconds captured when the workflow version was admitted/published (RF-MEM-01 Part F).	Omitted (inherits or disables this setting)
`memory_override_mb` Option<Value> Aliases: memoryMb, memory_mb, lambdaMemory, lambda_memory, workerMemory, workerMemoryMib, worker_memory_mib	Captures any forbidden user-supplied Lambda memory override (`memoryMb`, `lambdaMemory`, `workerMemoryMib`) so validation rejects it deterministically.	Omitted (inherits or disables this setting)
`role` Option<String> Aliases: iamRole, iam_role	Optional approved IAM role ARN or logical role alias assumed for this phase's execution. Overrides `WorkflowDef::default_role` when present.	Omitted (inherits or disables this setting)
`dedicated_handler_function_arn` Option<String> Aliases: dedicatedHandlerFunctionArn, dedicatedFunctionArn	Optional dedicated customer handler Lambda function ARN or name bound to this phase's customer IAM execution role (`IamIsolationBoundary::DedicatedLambdaExecutionRole`).	Omitted (inherits or disables this setting)
`isolation_boundary` Option<crate::iam_isolation::IamIsolationBoundary> Aliases: isolationBoundary	Optional explicit IAM isolation boundary (`dedicated_lambda_execution_role`, `hardened_subprocess_with_scoped_session`, or `shared_runner_no_aws_credentials`).	Omitted (inherits or disables this setting)
`runtime` Option<String>	Target execution runtime family (`"rust"` [default, no managed runtime], `"python"`, `"node"`, `"java"`). Also accepts inline `family:version` syntax such as `"python:3.12"`, `"node:22.x"`, or `"java:21"`.	Omitted (inherits or disables this setting)
`runtime_version` Option<String> Aliases: runtimeVersion	Optional runtime version pin (e.g. `"3.12"`, `"3.13"`, `"22.x"`, `"20.x"`, `"21"`, `"17"`, `"al2023"`).	Omitted (inherits or disables this setting)
`handler_uri` Option<String> Aliases: handlerUri, codeUri	Optional S3 URI (`s3://bucket/key`) or local path to pull the phase handler code dynamically into `/tmp/rippflow-handlers/`.	Omitted (inherits or disables this setting)
`handler_sha256` Option<String> Aliases: handlerSha256, codeSha256	Optional expected SHA-256 hex digest of the handler artifact fetched from `handler_uri`.	Omitted (inherits or disables this setting)
`entrypoint` Option<String>	Optional script, class, or binary entrypoint relative to `/var/task` or the downloaded bundle.	Omitted (inherits or disables this setting)
`scope` Option<PhaseScope>	Execution scope (`root`, `per_shard`, `fan_in_all`).	per_shard; terminal/orchestrator conventions use root
`mode` Option<ExecutionMode>	Execution mode (`async_sqs` or `sync_lambda`).	async_sqs via group routing
`terminal` bool	Marks this phase as a terminal completion node for the workflow.	false
`outcomes` HashMap<String, OutcomeRule>	Named outcome transition rules (e.g. `"completed"`, `"pass"`, `"rework"`, `"skipped"`).	Empty
`timeout` Option<String>	Optional phase execution timeout (e.g. `"2m"`, `"30m"`, `"10m"`, `"300s"`). Separate from Valkey coordination TTL; Rippflow derives active coordination retention so it is never shorter than `effective_phase_timeout_secs + recovery_margin`.	Omitted (inherits or disables this setting)
`wait_duration` Option<String> Aliases: waitDuration	Optional durable timer wait duration (e.g. `"30m"`, `"2h"`, `"1d"`). Suspends the phase in DynamoDB with zero active Lambda compute until `wakeAtEpochSecs`.	Omitted (inherits or disables this setting)
`wait_for_callback` bool Aliases: waitForCallback	Optional external callback wait gate (`true` when the phase suspends until an authenticated callback arrives).	false
`callback_timeout` Option<String> Aliases: callbackTimeout	Optional callback expiration window (e.g. `"1h"`, `"24h"`, default `"1h"` = 3600s).	1h when callback waiting is enabled
`sla` Option<SlaPolicy>	SLA timeout and retry bounds.	Omitted (inherits or disables this setting)
`type` Option<String>	Optional phase type (`"standard"` [default], `"loop"`, `"async_tool"`, `"governed_tool"`, or `"mcp_tool"`, RF-CONTROL-01 Part G, RF-AGENT-03 & RF-AGENT-04).	Omitted (inherits or disables this setting)
`tool` Option<String> Aliases: toolName, tool_name, toolId, tool_id	Optional logical tool identifier when `type: async_tool`, `type: governed_tool`, or `type: mcp_tool` (RF-AGENT-03 & RF-AGENT-04).	Omitted (inherits or disables this setting)
`tool_version` Option<String> Aliases: toolVersion	Optional pinned tool version when `type: governed_tool` or `type: mcp_tool` (e.g. `"1.0.0"`, RF-AGENT-04).	Omitted (inherits or disables this setting)
`tool_digest` Option<String> Aliases: toolDigest	Optional immutable tool definition digest (`rftool_v1_<sha256>`) pinned at workflow publication/admission (RF-AGENT-04).	Omitted (inherits or disables this setting)
`server_ref` Option<String> Aliases: serverRef	Optional registered MCP server reference when `type: mcp_tool` or `type: governed_tool` (e.g. `"internal-crm"`, RF-AGENT-04).	Omitted (inherits or disables this setting)
`callback` Option<crate::async_execution::AsyncCallbackSpec>	Optional authenticated callback contract when `type: async_tool` (RF-AGENT-03).	Omitted (inherits or disables this setting)
`retry` Option<crate::async_execution::AsyncRetrySpec>	Optional retry and backoff configuration when `type: async_tool` (RF-AGENT-03).	Omitted (inherits or disables this setting)
`adapter` Option<crate::async_execution::AsyncAdapterSpec> Aliases: asyncTarget, asyncAdapter	Optional provider-neutral external execution adapter when `type: async_tool` (RF-AGENT-03).	Omitted (inherits or disables this setting)
`controls` Option<crate::controls::WorkflowControlPolicy>	Optional phase-level execution controls (`limits`, `budgets`, `budget`, `hooks`, `gates`, RF-CONTROL-01 Part C & RF-AGENT-03).	Omitted (inherits or disables this setting)
`until` Option<crate::controls::LoopUntilSpec>	Required termination predicate (`resultPath`, `equals`) when `type: loop` (RF-CONTROL-01 Part G).	Omitted (inherits or disables this setting)
`body` Vec<crate::controls::LoopBodySubPhase>	Optional sub-phases executed inside a `type: loop` phase body (RF-CONTROL-01 Part G).	Empty

External lane

Option / type	Meaning	When omitted
`mode` ExecutionMode	async_sqs queues work; sync_lambda waits for a Lambda result.	See enum/default policy below
`target` String	SQS Queue URL (when `mode == AsyncSqs`) or Lambda Function ARN/name (when `mode == SyncLambda`).	Required
`concurrency_group` Option<String>	Optional JSONPath or key used for FIFO `MessageGroupId` / per-tenant concurrency grouping.	Omitted (inherits or disables this setting)

Outcome routing

Option / type	Meaning	When omitted
`next` Vec<String>	Explicit downstream phase keys to trigger for this outcome.	Empty
`rerun_phase` Option<String>	Optional upstream or current phase to re-run (e.g., QA rework loop back to a processor phase).	Omitted (inherits or disables this setting)
`max_loops` Option<u32>	Maximum number of rework loops permitted before escalating or failing (`default = 2`).	2 at execution
`advance_barrier` bool	Whether this outcome counts as a completed shard toward the phase's fan-in barrier.	false
`override_inputs` Option<Value>	Optional JSON object merged into the target phase's `inputs` when routing/rerunning.	Omitted (inherits or disables this setting)

Attempt SLA

Option / type	Meaning	When omitted
`timeout_secs` u32	Runner/watchdog attempt timeout in seconds.	300
`max_attempts` u32	Maximum attempts, including the initial attempt.	3

Coordination retention

Option / type	Meaning	When omitted
`defaultTtl` Option<String> Aliases: default_ttl	Default Valkey coordination TTL (e.g. `"15m"` or `"900s"`, default `900s` = 15 minutes).	Omitted (inherits or disables this setting)
`defaultTtlSecs` Option<u32> Aliases: default_ttl_secs	Optional explicit integer seconds for default coordination TTL.	Omitted (inherits or disables this setting)

Phase defaults

Option / type	Meaning	When omitted
`phaseTimeout` Option<String> Aliases: phase_timeout	Default phase execution timeout (e.g. `"5m"` or `"300s"`, default `300s` = 5 minutes).	Omitted (inherits or disables this setting)
`phaseTimeoutSecs` Option<u32> Aliases: phase_timeout_secs	Optional explicit integer seconds for default phase execution timeout.	Omitted (inherits or disables this setting)

Controls

Option / type	Meaning	When omitted
`policyVersion` u32	Control policy version; currently use 1.	1
`scope` Option<ControlScope>	Counter ownership boundary; see ControlScope values.	Omitted (inherits or disables this setting)
`budget` Option<String>	Optional shorthand reference to a workflow-level budget rule `id` (e.g. `controls: { budget: "research-budget" }`, RF-AGENT-03).	Omitted (inherits or disables this setting)
`limits` Option<ControlLimitsSpec>	Execution limits; nested fields cap counts, duration or concurrency.	Omitted (inherits or disables this setting)
`budgets` Vec<BudgetRuleSpec>	Resource allowance rules.	Empty
`hooks` BTreeMap<ControlEnforcementPoint, DecisionHookSpec>	Decision handlers keyed by enforcement point.	Empty
`gates` Vec<GateRuleSpec>	Approval gates before selected actions.	Empty

Execution limits

Option / type	Meaning	When omitted
`maxIterations` Option<u64>	Maximum loop iterations.	Omitted (inherits or disables this setting)
`maxPhaseExecutions` Option<u64>	Maximum phase executions, including rework.	Omitted (inherits or disables this setting)
`maxHandlerInvocations` Option<u64>	Maximum handler invocations.	Omitted (inherits or disables this setting)
`maxToolCalls` Option<u64>	Maximum tool calls.	Omitted (inherits or disables this setting)
`maxExternalRequests` Option<u64>	Maximum external requests.	Omitted (inherits or disables this setting)
`maxDuration` Option<String>	Maximum elapsed duration, e.g. 30m.	Omitted (inherits or disables this setting)
`maxConcurrentOperations` Option<u32>	Maximum simultaneous operations.	Omitted (inherits or disables this setting)
`maxChildWorkflows` Option<u32>	Maximum child workflows.	Omitted (inherits or disables this setting)
`maxRetries` Option<u32>	Maximum retries.	Omitted (inherits or disables this setting)
`maxRecoveryAttempts` Option<u32>	Maximum recovery attempts.	Omitted (inherits or disables this setting)
`violation` Option<ViolationAction>	Action when the limit is exceeded; see ViolationAction values.	Omitted (inherits or disables this setting)
`scope` Option<ControlScope>	Counter ownership boundary; see ControlScope values.	Omitted (inherits or disables this setting)
`reset` Option<ControlResetBehavior>	Counter reset policy; see ControlResetBehavior values.	Omitted (inherits or disables this setting)

Budget rule

Option / type	Meaning	When omitted
`id` Option<String> Aliases: name	Identifier within this containing object.	Omitted (inherits or disables this setting)
`resource` MeterResource	Metered resource; see MeterResource values below. Custom resource strings are also supported.	Required
`unit` String	Resource unit; use usd or usd_micros for money, tokens/calls/requests for counts, seconds or ms for compute.	Required
`limit` Value	Nonnegative allowance. USD is converted to fixed micro-dollars; count units require integers.	Required
`violation` ViolationAction	Action when the limit is exceeded; see ViolationAction values.	terminate
`enforcement` BudgetEnforcementMode	hard reserves before work; advisory records a soft limit.	hard
`maxExposurePerOp` Option<Value>	Maximum amount reserved for one operation before dispatch.	Omitted (inherits or disables this setting)
`scope` ControlScope	Counter ownership boundary; see ControlScope values.	workflow_run
`reset` ControlResetBehavior	Counter reset policy; see ControlResetBehavior values.	never

Decision hook

Option / type	Meaning	When omitted
`handler` String	Registered decision handler identifier.	Required
`timeout` String	Positive execution/expiration duration; see timeout precedence below.	5s
`onFailure` HookFailureAction	Hook failure action; see HookFailureAction values.	deny
`allowOpenOnNonSecurity` bool	Explicit opt-in for allow-on-error behavior; retain fail-closed policy for security decisions.	false

Approval gate

Option / type	Meaning	When omitted
`id` String	Identifier within this containing object.	Required
`enforcementPoint` ControlEnforcementPoint	Control check at which the gate is evaluated.	before_external_side_effect
`action` String	Action that requires approval.	Required
`target` String	Target resource or operation.	Required
`timeout` String	Positive execution/expiration duration; see timeout precedence below.	1h
`onTimeout` ViolationAction	Action when approval expires; see ViolationAction values.	terminate

Loop completion

Option / type	Meaning	When omitted
`resultPath` String	JSON result path tested for loop completion.	Required
`equals` Value	Value that ends the loop when matched.	Required

Loop body

Option / type	Meaning	When omitted
`id` String	Identifier within this containing object.	Required
`handler` String Aliases: service	Handler/service identifier executed inside the loop body.	Required
`kind` Option<String>	Optional loop sub-phase kind; use a handler for executable work.	Omitted (inherits or disables this setting)
`type` Option<String>	Sub-phase type; standard by default.	Omitted (inherits or disables this setting)
`inputs` Value	Application input passed to this handler.	null

Async callback

Option / type	Meaning	When omitted
`required` bool	Require the async completion callback.	true
`authenticated` bool	Require callback authentication.	true
`timeout` Option<String>	Maximum authenticated callback wait duration.	Inherits phase execution timeout
`allowedPrincipalArn` Option<String>	Approved IAM callback principal when IAM authentication is used.	Omitted (inherits or disables this setting)
`authMode` AsyncCallbackAuthMode	scoped_token_hmac, verified_iam_principal or dual_token_and_iam.	scoped_token_hmac

Async retry

Option / type	Meaning	When omitted
`maxAttempts` u32 Aliases: max_attempts	Maximum attempts, including the initial attempt.	3
`backoff` AsyncBackoffStrategy	exponential, linear or fixed retry delay.	exponential
`initialInterval` Option<String> Aliases: initial_interval	Initial async retry interval; falls back to 2s.	Omitted (inherits or disables this setting)
`maxInterval` Option<String> Aliases: max_interval	Maximum async retry interval; falls back to 60s.	Omitted (inherits or disables this setting)

External adapter

Option / type	Meaning	When omitted
`kind` AsyncAdapterKind	aws_lambda, external_https, ecs_task, cloud_run_job, azure_function or managed_ai_provider. Installation adapter support is required.	aws_lambda
`target` String	Target Lambda function ARN/name, HTTPS endpoint URL, container task definition, or provider URI.	Required
`idempotentDispatch` bool	Whether the external provider guarantees idempotent execution when supplied `idempotencyKey` / `invocationId`.	true
`supportsStatusLookup` bool	Whether the adapter supports querying operation status by `invocationId` when dispatch acknowledgement is lost.	false
`supportsRemoteCancel` bool	Whether the adapter supports active remote cancellation of an already-running external operation.	false
`providerName` Option<String>	Optional external provider name.	Omitted (inherits or disables this setting)
`modelId` Option<String>	Optional provider model identifier.	Omitted (inherits or disables this setting)

Enum values

Type	Accepted values
ExecutionMode	`async_sqs`, `sync_lambda`
ControlScope	`organization`, `tenant`, `project`, `workflow_definition`, `workflow_run`, `phase`, `loop`, `child_workflow`, `tool_invocation`
ControlEnforcementPoint	`before_admission`, `before_phase_dispatch`, `before_handler_invoke`, `before_external_side_effect`, `after_phase_completion`, `before_retry`, `before_callback_resume`, `before_child_workflow`, `before_recovery`, `on_budget_violation`, `on_deadline_exceeded`
ViolationAction	`deny`, `pause`, `retry_after`, `require_approval`, `terminate`, `quarantine`
HookFailureAction	`deny`, `pause`, `terminate`, `quarantine`, `allow`
BudgetEnforcementMode	`hard`, `advisory`
ControlResetBehavior	`never`, `per_phase`, `per_iteration`, `operator_amendment_only`
MeterResource	`iterations`, `handler_invocations`, `tool_calls`, `external_requests`, `tokens_input`, `tokens_output`, `model_cost`, `compute_seconds`
AsyncCallbackAuthMode	`scoped_token_hmac`, `verified_iam_principal`, `dual_token_and_iam`
AsyncBackoffStrategy	`exponential`, `linear`, `fixed`
AsyncAdapterKind	`aws_lambda`, `external_https`, `ecs_task`, `cloud_run_job`, `azure_function`, `managed_ai_provider`
IamIsolationBoundary	`dedicated_lambda_execution_role`, `hardened_subprocess_with_scoped_session`, `shared_runner_no_aws_credentials`
PhaseScope	`root`, `per_shard`, `fan_in_all`

Defaults & interactions

Execution timeout: phase timeout → sla.timeout_secs → defaults.phaseTimeout → 300 seconds. SLA attempts default to 3.
Timer waits use waitDuration; callback waits use waitForCallback and callbackTimeout (default 1h). Async-tool callback.timeout inherits its phase timeout.
Durations accept integer seconds or ms, s, m, h, d suffixes. Use positive durations. Coordination retention is separate from execution deadlines.

Advanced: external resources

A named lane overrides group routing. Its target may be an existing queue URL or Lambda ARN. External resources require appropriate IAM permissions.

yaml

name: external-resource-example
version: "1.0.0"
default_group: python-standard
lanes:
  external_check:
    mode: sync_lambda
    target: arn:aws:lambda:us-east-1:111122223333:function:external-check
phases:
  check:
    lane: external_check
    service: external-check
    terminal: true

Local CLI caveat: explicit phase-level groups normalize to queued execution. Use default_group for local mixed sync/async examples. Unknown phase keys and malformed wait durations can pass control validation; validation alone does not certify deployment.

Verified sources

Checked 2026-11-05.

workflow_def.rs 04cb082 · main
controls.rs 04cb082 · main
async_execution.rs 04cb082 · main
Managed runtime queues 3a3be99 · main
Application publication 7f5ea32 · main

Workflow definition reference

Choose where work runs

JSON

YAML

All definition options

Workflow

Phase

External lane

Outcome routing

Attempt SLA

Coordination retention

Phase defaults

Controls

Execution limits

Budget rule

Decision hook

Approval gate

Loop completion

Loop body

Async callback

Async retry

External adapter

Enum values

Defaults & interactions

Advanced: external resources

Contact Rippflow

We're looking for design partners

Search docs

Workflow definition reference

Choose where work runs

JSON

YAML

All definition options

Workflow

Phase

External lane

Outcome routing

Attempt SLA

Coordination retention

Phase defaults

Controls

Execution limits

Budget rule

Decision hook

Approval gate

Loop completion

Loop body

Async callback

Async retry

External adapter

Enum values

Defaults & interactions

Advanced: external resources

Related advanced guides

Contact Rippflow

We're looking for design partners