Flow Annotation Conventions

SEA™ Flows must include annotations to enable deterministic CQRS code generation.

Required: @cqrs

Every Flow must declare exactly one CQRS kind:

Flow "PlaceOrder"
  @cqrs { "kind": "command" }
  from "Customer" to "Order"
Value Meaning
"command" Write operation, mutates state
"query" Read operation, returns data
"event" Domain event, published after state change

Commands: Runtime Semantics

Flow "PlaceOrder"
  @cqrs { "kind": "command" }
  @tx { "transactional": true }
  @idempotency { "enabled": true, "key": "header:X-Idempotency-Key" }
  @outbox { "mode": "required" }
  from "Customer" to "Order"
Annotation Purpose
@tx Transaction boundary (transactional: true/false)
@idempotency Duplicate request handling (enabled, key)
@outbox Event publishing via outbox (mode: required/optional)

Queries: Read Model

Flow "GetOrder"
  @cqrs { "kind": "query" }
  @read_model { "source": "projection", "table": "order_read" }
  from "Customer" to "Order"
Annotation Purpose
@read_model Read source (primary_db, projection, cache)

Events: Publishing

Flow "OrderPlaced"
  @cqrs { "kind": "event" }
  @outbox { "mode": "required" }
  from "Order" to "Customer" quantity 1

CI Enforcement

tools/flow_lint.py validates:

1
2
3

just flow-lint
# or
python tools/flow_lint.py specs/<ctx>/<ctx>.sea