State & Memory Best Practices
Use explicit types and defaults
Every field should declare type and default. Rules assume missing fields exist with defaults.
Keep domain state separate from _tmp/
Saga scratch fields live under _tmp/. Do not store long-lived business data there — it is for process tracking only.
Prefer events + core rules over manual updates
Never patch snapshots from application code. Mutate through intents so every change is in the ledger.
Plan for replay after rule changes
Changing core rules changes how snapshots derive from history. Use Rebuilding Memory after non-additive rule changes.
Common mistakes
Storing large unbounded lists on entity state. Use relationships + projections for large many-to-many sets queryable at scale.
Using entity_id as a field name. Conflicts with envelope semantics in expressions.
Mixing projection data into entity snapshots for query convenience. Projections exist for read patterns; snapshots for authoritative per-entity state.
Next steps
- Examples — concert-app state YAML
- Rebuilding Memory — replay workflow
- Derived State — mental model