Workflows

A WorkflowSpec orchestrates multi-step processes. It defines the sequence of operations, handles failures with retries and compensation, and provides observability into long-running tasks.

Core concepts

Example WorkflowSpec (TypeScript)

Here's a simplified example of a payment workflow in TypeScript:

import { defineWorkflow } from '@contractspec/lib.contracts-spec/workflow';
import { ValidatePaymentMethod, ChargePayment, SendEmail } from './specs';

export const PaymentFlow = defineWorkflow({
  meta: {
    key: 'payment.flow',
    version: '1.0.0',
    description: 'End-to-end payment processing',
    owners: ['team-payments'],
    tags: ['payments'],
    stability: 'stable',
  },
  steps: [
    {
      id: 'validate-payment',
      operation: ValidatePaymentMethod,
      inputs: (ctx, input) => ({
        userId: ctx.userId,
        paymentMethodId: input.paymentMethodId,
      }),
      retry: {
        maxAttempts: 3,
        backoff: 'exponential',
      },
      onSuccess: 'charge-payment',
      onFailure: 'notify-user',
    },
    {
      id: 'charge-payment',
      operation: ChargePayment,
      inputs: (ctx, input, steps) => ({
        amount: input.amount,
        paymentMethodId: input.paymentMethodId,
      }),
      compensation: 'refund-payment',
      onSuccess: 'send-receipt',
      onFailure: 'notify-admin',
    },
    {
      id: 'send-receipt',
      operation: SendEmail,
      inputs: (ctx, input, steps) => ({
        to: ctx.userEmail,
        template: 'payment-receipt',
        data: steps['charge-payment'].output,
      }),
    },
  ],
  sla: {
    maxDuration: 30000, // milliseconds
    alertOnBreach: true,
  },
});

Triggers

Workflows can be triggered in several ways:

• Manual invocation – A user or system calls the workflow via an API endpoint.
• Event-driven – The workflow starts automatically when a specific event occurs (e.g., a new order is created).
• Scheduled – The workflow runs on a cron schedule (e.g., nightly batch processing).
• Chained – One workflow can invoke another as a step.

Monitoring and versioning

ContractSpec automatically instruments workflows with telemetry. You can view:

• Real-time execution status for each step
• Historical run data and success/failure rates
• Latency distributions and SLA compliance
• Compensation events and retry attempts

When you update a workflow, you increment its version. Running workflows continue on their original version, while new invocations use the latest version. This allows safe, zero-downtime deployments.

Best practices

• Keep steps idempotent – they should be safe to retry without side effects.
• Define compensation for any step that modifies external state.
• Use meaningful step IDs that describe the operation.
• Set realistic SLAs and monitor them in production.
• Test failure scenarios locally before deploying.