grain-command-handler
Implement command handlers that validate state and emit events using the Grain framework
SKILL.md.claude/skills/grain-command-handler/SKILL.md
GitHubGrain Command Handler Pattern
Required Imports
(ns my.service.core.commands
(:require [ai.obney.grain.event-store-v3.interface :refer [->event]]
[ai.obney.grain.command-processor-v2.interface :refer [defcommand]]
[ai.obney.grain.command-processor-v2.interface :as cp]
[ai.obney.grain.time.interface :as time]
[my.service.core.read-models :as rm]
[cognitect.anomalies :as anom]))
Command Template
(defcommand :service command-name
"Docstring describing what the command does."
[{{:keys [entity-id field1 field2]} :command
:as ctx}]
;; 1. Read current state from read models (pass ctx, NOT bare event-store)
(let [entity (rm/get-entity ctx entity-id)]
(cond
;; Return anomaly for validation failures
(not entity)
{::anom/category ::anom/not-found
::anom/message "Entity not found"}
(not (:active entity))
{::anom/category ::anom/conflict
::anom/message "Cannot modify inactive entity"}
;; Success: return events
:else
{:command-result/events
[(->event
{:type :service/entity-updated
:tags #{[:entity entity-id]}
:body {:entity-id entity-id
:field1 field1
:field2 field2
:modified-at (str (time/now))}})]})))
Key Variations
Success with Events Only
{:command-result/events
[(->event {:type :service/thing-created
:tags #{[:thing thing-id]}
:body {:thing-id thing-id :name name}})]}
Anomaly Return (Error)
{::anom/category ::anom/conflict
::anom/message "Name already taken."}
CAS (Optimistic Concurrency)
Prevents races by checking state hasn't changed between read and write:
{:command-result/events [...]
:command-result/cas {:types thing-event-types
:predicate-fn (fn [_events]
(= :active (:status (rm/get-thing ctx id))))}}
Calling Other Commands
(let [result (cp/process-command
(assoc ctx :command {:command/id (random-uuid)
:command/timestamp (time/now)
:command/name :other/command-name
:field1 value1}))]
;; result is either anomaly or {:command-result/events [...]}
result)
Common Anomaly Categories
::anom/not-found-- resource does not exist::anom/conflict-- business rule violation (duplicate, invalid state)::anom/incorrect-- bad input data::anom/forbidden-- not authorized for this action
Conventions
- Commands modify state by emitting events; never write to a database directly
- Always validate via read models before emitting events
- Read model helpers take
ctx(the full context), not bareevent-store - Tag events with
#{[:entity entity-id]}for efficient filtered reads - Return anomalies for all error cases
- Include
modified-atin event bodies when relevant
Reference Files
components/orc-service/src/ai/obney/orc/orc_service/core/commands.clj-- ORC sheet commandscomponents/colbert/src/ai/obney/orc/colbert/core/commands.clj-- ColBERT commandscomponents/ontology/src/ai/obney/orc/ontology/core/commands.clj-- Ontology commands