Intents Overview
An intent is a declared command submitted by a client. The runtime evaluates it against your rules in three phases — preflight, core, and side effects — then commits events to the ledger.
Intents are how you model commands in an event-sourced system: validate input, change state, emit facts.
How intents fit into the write path
Write path: Client submits an intent → runtime loads entity state → rules run → ledger updated → events published.
Read path: Events are consumed asynchronously by projections. Queries read projection tables — never the ledger directly.
Three rule phases
| Phase | Runs when | Purpose |
|---|---|---|
| Preflight | Before any write | Validate input and business rules; reject on failure |
| Core | After preflight passes | Mutate target entity state |
| Side effects | After ledger commit | Emit events, submit follow-up intents, schedule timers |
A rejection in preflight returns an error with zero state changes.
Declaring intents
Intents are declared in .actions.causet files under the actions: key, included from app.causet:
includes:
actions: [./actions/**/*.actions.causet]Each entry declares an input schema, target state stream, entity_id_expr, and rule blocks. The compiler validates ops and event references at build time.
Note: The DSL section is named
actions:and files use the.actions.causetextension. At runtime these are submitted and processed as intents.
In this section
| Page | What it covers |
|---|---|
| Concept | Why intents exist, determinism, write vs read path |
| Defining Intents | Input schema, entity routing, full anatomy |
| Rules | Preflight, core, side_effects phases |
| Operations | Every rule op with required fields |
| Expressions | Expression syntax and forbidden functions |
| Idempotency | Retry-safe intents, deterministic IDs, at-least-once |
| Correlation & Causation | Tracing intent chains and user requests |
| Best Practices | Production guidance and common mistakes |
| Examples | Concert-app patterns and links to tutorials |
Next steps
- Events — events intents emit
- Projections — read models derived from those events
- Queries — named reads over projections