Workflow Best Practices

Use sagas for single-entity process tracking

Ticket import, checkout, onboarding — one entity, many steps, preflight gates on _tmp/saga_step.

Use submit chains for cross-entity fan-out

Enrichment on artist, notification on user, billing on order — each step is its own intent with its own audit trail.

Keep _tmp/ for process state only

Do not store durable domain fields under _tmp/. Promote to regular fields when the process completes.

Design explicit failure steps

Sagas without error terminal states stall silently. Model on: TICKET_PARSE_FAILED → step with end: true and _tmp/error_code.

Common mistakes

Using sagas for cross-service orchestration with external I/O. Submit intents from a worker that calls external APIs, then emits results back.

Expecting saga rollback. Causet does not auto-compensate. Model explicit undo intents or events.

Long timers inside Causet. schedule is relative and short-lived. Use external cron → intent submit for daily jobs.

Omitting preflight saga checks. Gate actions with entity._tmp.saga_step so out-of-order events reject cleanly.

Forgetting when: guards on steps. Two steps reacting to the same event without mutually exclusive when: conditions can both fire. Gate on current saga state.

Not declaring _tmp/ fields in state. Reference only fields declared on the entity state: block — undeclared paths have undefined runtime behavior.

Putting I/O in saga step transitions. Steps are rule evaluations only. Emit events in side_effects for external work.

Using sagas for cross-entity workflows. Sagas are single-entity. Use submit in side_effects for other streams.

Next steps

• Examples — ticket import and purchase sagas
• Error Handling — recovery patterns
• Defining Sagas — DSL reference