Workflows & Durable Execution

Some work finishes in a single request. Other work is long-running: it retries on failure, waits on a human decision, fans out notifications, and must survive a service restart in the middle. Atelier treats this durable execution as a first-class capability — and, like everything else on the platform, you reach it by declaring an action, not by writing orchestration code.

The core promise is simple: the moment a durable action is accepted, the work is durable. Atelier records the request as a durable ledger entry — the submission — and returns success immediately, before any downstream entity is created and even if a backing service is temporarily unavailable. The platform then drives the request to completion in the background, retrying as needed, and materializes the real record when the work succeeds.

This is how a declared action becomes a durable, retryable, human-in-the-loop process with no bespoke code. You declare the interesting part — the contract for what should happen — and Atelier provides the durable machinery that makes it happen reliably.

The submission: durable from the first millisecond

Every durable action centers on a submission: a thin, vertical-agnostic ledger entry written the instant a workflow-mode action is accepted.

• The acknowledgement is durable before any entity exists. If a backing service is briefly down, the submission is still safely recorded and will be completed later.
• Each submission carries a stable reference you can track from the moment it's accepted.
• Duplicate submissions are detected and quarantined rather than silently creating twins.

Once the submission is recorded, a generic workflow drives it forward: normalize the payload, validate it, check for duplicates, prepare and create the real entity, attach related files, and write an audit trail — then complete. Because this pipeline is generic, every vertical reuses it; there is no per-vertical orchestration to build.

Two tiers of execution

Atelier splits durable work cleanly:

Tier	Runs	Use it for
In-process workflows	Inside Atelier	Fast, tightly-scoped durable steps such as notification fan-out
Martha-backed workflows	On the Martha workflow engine	Long-running, multi-step, human-in-the-loop, and reactive processes

Martha is Atelier's workflow backbone. Atelier hands heavier orchestration to Martha over a standards-based event bridge (CloudEvents), and Martha calls back into Atelier to materialize results. You get durable retries, timers, and human-pause steps without standing up your own orchestration layer.

Declare, don't code

You author durable execution as data on an action, never as imperative code.

To make an action durable, set its execution mode to workflow and author its submission contract — a small piece of declarative JSON that names each step of the durable-create pipeline:

actions:
  - key: submit_report
    label: Submit a report
    target_model: report
    execution_mode: workflow
    status: published
    is_active: true
    permissions_policy:
      view: ["admin", "citizen"]
      apply: ["admin", "citizen"]
      edit: ["admin"]
    parameters:
      - { key: title, label: Title, type: string, required: true, order: 10 }
      - { key: description, label: Description, type: string, required: true, order: 20 }
      - { key: location, label: Location, type: geo, required: true, order: 30 }
    creates:
      - key: report
        entity_type: report
        fields:
          status: received
          title: $parameters.title
          description: $parameters.description
          location: $parameters.location
    submission_contract:
      reference:
        field: public_ref
        format: "{prefix}-{year}-{seq:03d}"
      attachments:
        entity_type: report_attachment
        parent_field: report
        file_field: file
        allowed_content_types:
          - image/jpeg
          - image/png
          - application/pdf
        max_bytes: 26214400

Each step references a registered, named function drawn from a curated library — never inline code. This keeps contracts safe, reviewable, and portable across verticals. A single generic engine interprets the contract, so the same machinery serves every application you build.

Synchronous actions are the immediate sibling of durable ones — see The Action Engine for the engine-mode path. You choose per action whether it runs inline or as a durable workflow.

Notifications ride the same rails

Durable side effects — most commonly notifications — are also declared, not coded. Adding one is a short authoring path:

1. Declare the emit. On the action's Effects tab, add a side effect that emits a notification event.
2. Subscribe to it. Author one or more notification rules that react to the event, each pointing at an operator-editable template.

Rules and templates are tenant-scoped, support per-tenant precedence, and fan out through a durable in-process workflow so a transient channel outage doesn't lose the message. Engine-mode actions emit on execute; submission-mode actions emit at accept time. See Notifications for the full authoring surface.

Tenancy: declared once, forked everywhere

Durable execution travels with your tenants automatically. Submission contracts, notification rules, templates, and declared side effects all live on the application definition. When you stand up a new tenant from a template application, the full catalog is copied and re-wired as part of the standard fork — so a freshly provisioned tenant's workflow-mode actions and notification fan-out work immediately, with no special-case setup. See Provisioning & the Fork for how templating works.

Built-in guarantees

Atelier's durable execution layer holds these properties by construction:

• Accept-when-degraded. The submission ledger entry is durable before any entity is created. A momentary outage in a backing service never loses an accepted request.
• Fire-and-forget emission never fails an action. Handing work to the workflow backbone cannot fail the originating action; a downstream outage is absorbed, logged, and retried — never surfaced as a user-facing failure.
• Exactly-once creation. Deduplication is anchored to a deterministic workflow identity that survives retries and replays, so a retried submission produces exactly one real entity.
• Retry-safe callbacks. Re-entry on an already-completed submission only re-runs idempotent post-create effects — never a second creation.
• Tenant-bound by construction. Every durable callback is bound to the tenant recorded on its own submission, derived from verified identity — never from inbound request headers. Requests that can't be tenant-resolved are refused. This makes the path tenant-isolated and fail-closed.
• Identity-derived ownership. Owner and actor fields come only from the validated caller identity, never from the request body. Service identities are transport, never recorded as the human reporter.
• No secrets on the wire. Event payloads are scrubbed of secret-shaped fields before they ever leave Atelier, and service-to-service authentication is verified safely.
• Tenant-scoped fan-out. Notification-rule lookup is always tenant-scoped, so an event fans out through one tenant's rules and never another's.

Human-in-the-loop

Durable workflows can pause for a human and resume on their decision. Atelier surfaces lightweight in-product checkpoints — for example, a confirm-or-override step when a submission looks like a duplicate — while longer-running approval and review flows run as Martha workflows keyed off the same event stream. Because the wait is durable, a process can sit idle for minutes or days and pick up exactly where it left off.

Extension points

The durable layer is designed to grow by declaration:

• A new durable-create vertical — declare a workflow-mode action with a submission contract. The generic intake, event bridge, and create-entity callback handle it with no new code.
• New contract-step behavior — register a named function and reference it from a contract.
• A new durable notification — declare a side effect and author a notification rule.
• A new reactive workflow — author a trigger and workflow in Martha keyed off an existing or new event type; Atelier simply emits the event.

How it fits together

Declared action (workflow mode)
        │  accepted
        ▼
   Submission ledger  ──►  202, durable immediately
        │  event (CloudEvents)
        ▼
   Workflow engine (Martha)
        │  normalize → validate → dedup → create → attach → audit
        ▼
   Real entity materialized  ──►  notifications fan out

You declare the contract. Atelier and Martha provide the durable, retryable, observable execution underneath it.