Events, Intents & Sagas

Errors from the events:, intents:, and sagas: blocks, plus general Product DSL structural checks.

17 error codes in this section.

Event Errors

VERR_EVENT

General event validation failure. An event type referenced in a rule does not match any event registered in the spec.

Impact: Emit is dropped; downstream projections that depend on the event never fire.

ops:
  - op: emit
    event_type: OrderShipped   # not in app.causet

# Register OrderShipped in app.causet.

VERR_EVENT_NOT_DECLARED

Emitting undeclared event. A rule emits an event type that has no corresponding entry in the event registry.

Impact: Emit is silently dropped; no projection or listener will receive the event.

ops:
  - op: emit
    event_type: OrderShipped    # not in app.causet

# Add OrderShipped to app.causet:
events:
  OrderShipped:
    payload:
      order_id: string
      shipped_at: timestamp

VERR_EVENT_SCHEMA_MISMATCH

Event payload does not match schema. The event payload being emitted contains undeclared fields or omits required fields.

Impact: Projection workers receive unexpected null values or extra fields that are silently discarded.

ops:
  - op: emit
    event_type: OrderPlaced
    payload:
      mystery_field: "x"    # not in OrderPlaced schema

# Only emit payload fields declared in the event schema.
# Add missing fields to app.causet if needed.

VERR_EVENT_IMMUTABLE_VIOLATION

Event derived from mutable entity state. An emitted event’s payload reads entity state fields that are mutable and could change between the original write and a replay.

Impact: Replay produces different event payloads; downstream projections diverge.

# Reads mutable entity.price into event payload
payload:
  price: "#{ entity.price }"

# Build event payloads from intent payload fields only.

VERR_EVENT_INTENT_NAME_COLLISION

Event and intent share the same name. An event type name is identical to an intent type name, making routing ambiguous.

Impact: The runtime may route events to intent handlers and vice versa.

events:
  PlaceOrder: {}   # same name as intent PlaceOrder

# Use past tense for events:
events:
  OrderPlaced: {}

VERR_CROSS_STREAM_EVENT_ILLEGAL

Emitting event to stream you don’t own. A rule emits an event that is declared as belonging to a different stream.

Impact: Event is rejected; the target stream’s listeners do not fire.

# orders_stream emitting UserEvent owned by users_stream

# Only emit events declared for your own stream.
# Use cross-stream intents for cross-boundary coordination.

Intent Errors

VERR_INTENT_NOT_DECLARED

Rule handles undeclared intent. A rule’s when.intent_type references an intent that is not declared in app.causet.

Impact: Rule is dead — it will never fire.

rules:
  handle_place:
    when:
      intent_type: PlaceOrder    # not in app.causet

# Add PlaceOrder to app.causet:
intents:
  PlaceOrder:
    payload:
      product_id: string

VERR_INTENT_SCHEMA_MISMATCH

Rule accesses undeclared intent field. A rule reads an intent payload field that is not declared in the intent schema.

Impact: Field evaluates to null at runtime; rule writes incorrect values.

# discount_code not in PlaceOrder schema
value: "#{ intent.payload.discount_code }"

# Add discount_code to PlaceOrder in app.causet,
# or remove the reference from the rule.

VERR_AMBIGUOUS_INTENT_HANDLER

Multiple rules handle same intent ambiguously. Two or more rules handle the same intent type without mutually exclusive guards.

Impact: Runtime executes both rules; state mutations are duplicated.

rules:
  handle_a: { when: { intent_type: PlaceOrder } }
  handle_b: { when: { intent_type: PlaceOrder } }   # ambiguous

# Add mutually exclusive when.condition guards,
# or merge the logic into a single rule.

VERR_UNHANDLED_INTENT

Declared intent has no handler. An intent is declared in app.causet but no rule handles it.

Impact: Clients receive an error when they submit the intent — no rules will process it.

# app.causet declares PlaceOrder
# But no rule has when.intent_type: PlaceOrder

# Add a handler rule, or remove the intent declaration.

VERR_INTENT_EVENT_CONFLICT

Rule specifies both intent_type and event_type. A single when block specifies both intent_type and event_type.

Impact: Rule routing is ambiguous; rule may fire on the wrong trigger.

when:
  intent_type: PlaceOrder
  event_type: OrderCreated    # cannot have both

# A rule listens to either an intent or an event — not both.
# Split into two separate rules.

Workflows (Sagas)

VERR_SAGA

Invalid saga definition. A saga in the sagas: block has an invalid state reference, a malformed state_path, a duplicate step name, or a step whose on: event isn’t declared. Sagas compile to ordinary event-triggered core rules that merge into state_path, so every reference must resolve just like a normal rule.

Impact: Compilation aborts — the saga’s generated rules are never produced, so entity state stops advancing past the last valid step.

sagas:
  show_publish:
    state: nonexistent_state   # no such state declared
    state_path: /_tmp/show_publish
    steps:
      - name: draft_saved
        on: SHOW_DRAFT_SAVED
        set: { status: draft }

sagas:
  show_publish:
    state: show                # must match a declared state
    state_path: /_tmp/show_publish
    steps:
      - name: draft_saved
        on: SHOW_DRAFT_SAVED
        set: { status: draft }

Product DSL

VERR_PRODUCT_STRUCTURE

Product DSL structural error. The Product DSL Causet DSL has a structural error — unsupported version, unknown top-level key, or missing app block.

Impact: The entire product spec is rejected; nothing is compiled.

version: 99   # unsupported
projections: {}

version: 1
app:
  name: my-app
projections: {}

VERR_PRODUCT_STATE_REF

Unknown state reference in product spec. A projection, listener, or relationship references a state name that does not exist under the state: key.

Impact: The referencing block is compiled with a null entity reference; runtime loads wrong or no entities.

projections:
  checkins:
    resolver:
      venue:
        entity: venue   # 'venue' not in state:

state:
  venue: { ... }
# then the resolver resolves correctly

VERR_PRODUCT_EVENT_REF

Unknown event reference in product spec. A projection source_events list contains an event type that has no corresponding definition.

Impact: Projection never fires; it materialises no rows.

projections:
  checkins:
    source_events:
      - CheckedIn    # not defined

# Add CheckedIn to the event definitions first.

VERR_PRODUCT_INTENT_IN_RULE

Intent type used in product rule. A product-level rule specifies when.intent_type, which is not allowed. Product rules react to events only.

Impact: Rule is dead — product rules can only be triggered by events.

rules:
  handle_place:
    when:
      intent_type: PlaceOrder   # not allowed in product rules

rules:
  handle_place:
    when:
      event_type: OrderPlaced

VERR_PRODUCT_FIELD_TYPE

Unrecognised field type in product spec. A field type in the Product DSL is not one of the supported types.

Impact: DDL generation uses TEXT as fallback; type-sensitive ops produce wrong results.

fields:
  score: float64   # not supported

fields:
  score: DOUBLE