Skip to content

Workflow — Saga design as workflow definitions

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
Workflow id saga-design · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04)
Coordinator saga-flow-designer · family Event-Driven Architecture & Messaging
Owner service WorkflowEngineService (BC-38) under Run Control (BC-03)
Starts on DomainModelDerived from BlueprintService (event)
Steps 4 · gated 0 · agents 2
Budget per run 600000 tokens · cap 60.0 USD · 240 min
Descriptor workflow-definition-v1 · schema
Status target

Finds the long-running flows in a derived domain model and designs each as a workflow definition with compensation, validated against the DSL, instead of an ad-hoc saga.

Authored design, Draft (D54, D57)

These definitions were authored on 2026-10-14 from the coordinator cards as design assumptions. None is published, evaluated or has run; agents are named by id as design bindings, not as tested integrations.

Definition

flowchart TD
    start(("DomainModelDerived"))
    identify_flows["Identify long-running flows"]
    design_compensation["Design compensation"]
    draft_definitions["Draft the definitions"]
    validate{"Validate against the DSL"}
    start --> identify_flows
    identify_flows --> design_compensation
    design_compensation --> draft_definitions
    draft_definitions --> validate
    done(("WorkflowRunCompleted"))
    validate --> done
    classDef gated stroke:#B45309,stroke-width:2px
Hold "Alt" / "Option" to enable pan & zoom

Shapes: rectangle = agent attempt · double rectangle = tool call · stadium = human decision · diamond = condition evaluated by the engine · parallelogram = fan-out or join · circle = timer · cylinder = sub-workflow · flag = compensation. A thick amber border marks a gated step.

Steps

# Step Kind Runs Gate Class Depends on Retry Timeout Compensation What it does
1 Identify long-running flows
identify-flows		 agent event-driven-architect none read — exponential ×2 PT30M — Finds the multi-context, multi-step flows and their failure points in the domain model.
2 Design compensation
design-compensation		 agent event-driven-architect none read identify-flows exponential ×2 PT30M — Defines the compensation of every effectful step and the idempotency keys.
3 Draft the definitions
draft-definitions		 agent enterprise-architect none sandbox design-compensation exponential ×2 PT30M — Writes one workflow definition per flow with steps, gates, timers and compensation.
4 Validate against the DSL
validate		 condition engine none sandbox draft-definitions fixed ×2 PT2M — Each definition validates against workflow-definition-v1. Condition: definitions.valid.

Gates and approvals

No approval is required: every step runs in the read or sandbox class; the agents' own tool calls still carry their classes (D21). Compensation steps run in reverse order of the succeeded steps on failure after the last checkpoint; a step without a compensation leaves its sandbox output in place and the run ends Failed with the evidence (ADR-0014, recovery not replay).

Inputs, outputs and events

Direction Name Descriptor
in domain-model artifact-v1
out workflow-definitions workflow-definition-v1

Starts on DomainModelDerived; emits ArtifactStored, plus the engine's WorkflowRunStarted, StepReady, StepRunStateChanged and WorkflowRunCompleted / WorkflowRunFailed and Run Control's run and attempt events (ADR-0014).

Decisions and traceability

FR: FR-10 RecoveryXL: XL-06 Recover without repeating an effectADRs: ADR-0012, ADR-0014, ADR-0024 · ADR index

Definition authored 2026-10-14 from the coordinator card saga-flow-designer (D54); Draft until an evaluation gate (ADR-0021) and a review publish it as a BC-04 asset release.