adk_workflow (erlang_adk v0.7.0)

Declarative, bounded workflow API.

A compiled workflow is immutable. Each started workflow has a detached coordinator which owns its checkpoint and terminal outcome; potentially blocking actions execute in monitored workers. Public checkpoints contain JSON-safe values only and can be used to resume from the last committed boundary with the remaining non-time budgets intact.

Summary

Types

checkpoint/0

outcome/0

workflow_ref/0

Functions

await(Ref)

await(Ref, Timeout)

cancel(Ref)

cancel(Ref, Reason)

checkpoint(Ref)

compile(Spec)

Validate and compile a declarative workflow specification.

delete_invocation(InvocationId, Opts)

Delete an unowned durable invocation from its ledger.

exception_reason(Component, Operation, Class, Reason)

external_reason(Component, Operation, Failure)

failure_reason(Failure)

initial_checkpoint(Compiled, State, Runtime)

invocation_status(InvocationId, Opts)

Read persisted invocation state without requiring a live coordinator.

is_compiled(_)

prepare_resume_checkpoint(Compiled, Checkpoint, Opts)

public_invocation_record(Record)

resume(Compiled, Checkpoint)

resume(Compiled, Checkpoint, Opts)

resume_invocation(InvocationId, Compiled, Opts)

Claim and resume a durable workflow by stable invocation ID.

run(Compiled, InitialState)

run(Compiled, InitialState, Opts)

sanitize_reason(Reason)

start(Compiled, InitialState)

start(Compiled, InitialState, Opts)

start_invocation(Compiled, InitialState, Opts)

Start a checkpointed workflow with a stable durable invocation ID.

status(Ref)

terminal_outcome(Phase, Reason, Checkpoint)

validate_checkpoint(Compiled, Checkpoint)

Types

checkpoint/0

-type checkpoint() :: map().

outcome/0

-type outcome() ::
          {completed, map(), checkpoint()} |
          {paused, map(), checkpoint()} |
          {failed, term(), checkpoint()} |
          {timed_out, checkpoint()} |
          {cancelled, term(), checkpoint()}.

workflow_ref/0

-type workflow_ref() :: pid().

Functions

await(Ref)

-spec await(workflow_ref()) -> outcome() | {error, term()}.

await(Ref, Timeout)

-spec await(workflow_ref(), timeout()) -> outcome() | {error, term()}.

cancel(Ref)

-spec cancel(workflow_ref()) -> ok | {error, term()}.

cancel(Ref, Reason)

-spec cancel(workflow_ref(), term()) -> ok | {error, term()}.

checkpoint(Ref)

-spec checkpoint(workflow_ref()) -> {ok, checkpoint()} | {error, term()}.

compile(Spec)

-spec compile(map()) -> {ok, map()} | {error, term()}.

Validate and compile a declarative workflow specification.

delete_invocation(InvocationId, Opts)

-spec delete_invocation(binary(), map()) -> ok | {error, term()}.

Delete an unowned durable invocation from its ledger.

exception_reason(Component, Operation, Class, Reason)

external_reason(Component, Operation, Failure)

failure_reason(Failure)

initial_checkpoint(Compiled, State, Runtime)

invocation_status(InvocationId, Opts)

-spec invocation_status(binary(), map()) -> {ok, map()} | {error, term()}.

Read persisted invocation state without requiring a live coordinator.

is_compiled(_)

prepare_resume_checkpoint(Compiled, Checkpoint, Opts)

public_invocation_record(Record)

resume(Compiled, Checkpoint)

-spec resume(map(), checkpoint()) -> {ok, workflow_ref()} | {error, term()}.

resume(Compiled, Checkpoint, Opts)

-spec resume(map(), checkpoint(), map()) -> {ok, workflow_ref()} | {error, term()}.

resume_invocation(InvocationId, Compiled, Opts)

-spec resume_invocation(binary(), map(), map()) -> {ok, workflow_ref()} | {error, term()}.

Claim and resume a durable workflow by stable invocation ID.

Exactly one live coordinator can own an invocation. A dead local owner is replaced immediately; a remote owner can be replaced only after its lease expires. Completed invocations are immutable and cannot be resumed.

run(Compiled, InitialState)

-spec run(map(), map()) -> outcome() | {error, term()}.

run(Compiled, InitialState, Opts)

-spec run(map(), map(), map()) -> outcome() | {error, term()}.

sanitize_reason(Reason)

start(Compiled, InitialState)

-spec start(map(), map()) -> {ok, workflow_ref()} | {error, term()}.

start(Compiled, InitialState, Opts)

-spec start(map(), map(), map()) -> {ok, workflow_ref()} | {error, term()}.

start_invocation(Compiled, InitialState, Opts)

-spec start_invocation(map(), map(), map()) -> {ok, binary(), workflow_ref()} | {error, term()}.

Start a checkpointed workflow with a stable durable invocation ID.

Opts must contain ledger => {Module, Handle}, where Module implements adk_invocation_ledger. The returned ID, unlike the coordinator pid, stays valid across coordinator and VM/application restarts. An optional binary invocation_id may be supplied for upstream idempotent creation.

status(Ref)

-spec status(workflow_ref()) -> {ok, map()} | {error, term()}.

terminal_outcome(Phase, Reason, Checkpoint)

validate_checkpoint(Compiled, Checkpoint)