Conseqa State Machines and Transition Side Effects

A state machine defines the legal states and legal transitions of a persistent object field.

Declaration

state_machines:
  machine.order_lifecycle:
    subject:
      kind: object
      object: obj.Order
      state: status
    initial: pending
    states:
      - pending
      - paid
      - shipped
      - cancelled
    transitions:
      transition.order.mark_paid:
        from:
          - pending
        to: paid
        side_effects:
          effect.order.paid:
            kind: publication
            topic: topic.order_events
            schema: schema.OrderPaid
            idempotency_key_propagation: []

Key fields

object : The persistent object class governed by this machine.
state : The field in the object’s canonical schema that stores the logical machine state.
initial : The initial state for a newly created logical machine instance. It does not imply that every existing persistent record is currently in that state.
Transition.from : The set of states from which this transition is legal.
Transition.to : The destination state.

The state machine declares legality, not concurrency safety. Two individually legal transitions can still race. The verifier must use isolation, locks, serialization, ordering, or other facts to prove that concurrent execution cannot produce an illegal history.

Applying a transition

A transition transaction step selects a concrete persistent machine instance and applies the named transition:

- kind: transition
  machine: machine.order_lifecycle
  transition: transition.order.mark_paid
  subject:
    object: obj.Order
    predicate:
      kind: eq
      field: order_id
      value:
        source: input:input.apply_payment.captured
        path: order_id
  effect_intents:
    effect.order.paid:
      bind: intent.order_paid
      values:
        kind: deterministic
        from:
          - source: input:input.apply_payment.captured
            path: order_id

The state transition guard and update to the destination state are interpreted as one logical state transition within the surrounding transaction.

Transition transactions are never naturally replayable

A transaction containing any Transition is not naturally replayable under the current replay proof rules. A successful transition changes the state against which its own precondition was evaluated, so re-executing the transaction cannot generally be assumed to reproduce the same transaction outcome or transaction artifacts. This is a proof fact, not a structural validity rule. A transition-containing transaction may declare any IdempotencyGuarantee permitted for other transactions, and deduplicated_by { key } provides the durable recovery route: after the first successful logical commit, a later same-key encounter resolves the prior commit and restores the exact retained artifacts. Without deduplicated_by, no declared fact makes the transition’s artifacts replay-available, and obligations that need them settle unproven.

Transition side effects

A transition may declare publication or request side effects associated with taking that transition. These are shared model-level declarations: a state machine exists independently of any one operation and may be applied by several. For replay semantics, these side effects are treated as implicitly established effect-intent transaction artifacts when the transition successfully commits. They are not direct external executions inside the application-state transaction.

Transition effect intents

The state-machine transition owns the effect contract; the applying transition transaction step owns the concrete instance provenance and the artifact binding. effect_intents maps each side effect declared by the applied transition to a TransitionEffectIntent: the operation-local bind and the Derivation used to construct that side effect’s instance. The mapping must be exact:

transition.side_effects.keys()
==
state_transition.effect_intents.keys()

Each entry supplies exactly one concrete derivation and one operation-local intent binding. Missing entries, extra entries, and entries keyed by another transition’s effects are all structural validation errors. A transition without side effects declares an empty map. Each derivation is evaluated in the enclosing transaction context at the point of the transition step, and may reference operation-level values, transaction outputs available at that point, and preceding transaction_read bindings.

Important restrictions

A transition side effect must never be established via establish_effect_intent nor executed via execute_effect directly. Its ID belongs to the state machine’s declaration, so an inline site claiming it is a DuplicateId. Establishment is the transition’s responsibility, and execution is ExecuteEffectIntent’s. A successful transition transaction logically performs the following atomically:

evaluate the state-transition guard
apply the state transition
construct each transition side-effect instance using its corresponding derivation
establish each bound effect-intent artifact
commit the transition state and established artifacts together

When the transaction declares DeduplicatedBy { key }, these derivations are evaluated only during the first successful keyed execution. A retry with the same transaction idempotency identity resolves Commit(T,K) and recovers the exact original artifacts without evaluating the derivations again.

Get Started

Core Concepts

Runtime Topology

DSL Reference

Verification

Visualization

Guides

Conseqa State Machines and Transition Side Effects

Declaration

Key fields

Applying a transition

Transition transactions are never naturally replayable

Transition side effects

Transition effect intents

Important restrictions

​Declaration

​Key fields

​Applying a transition

​Transition transactions are never naturally replayable

​Transition side effects

​Transition effect intents

​Important restrictions

Declaration

Key fields

Applying a transition

Transition transactions are never naturally replayable

Transition side effects

Transition effect intents

Important restrictions