Decisions

A decision is the kernel asking a question it cannot answer alone.

Most extension models push in the other direction: the platform does something and tells you afterwards, via a webhook, and if you disagree you compensate. That works for notifications and fails for anything the outcome depends on — you cannot un-reserve stock from the wrong warehouse gracefully.

Decisions invert that. The kernel stops, asks, and uses the answer.

What one looks like

A decision is declared: it has a name, a question shape and an answer shape, and both are part of the contract. Your implementation receives the question and returns an answer, synchronously, inside the transaction the command is running in.

That last part is the whole point. The answer is not applied later or reconciled afterwards — it is a parameter of the change being made. If your answer never comes, the command fails and nothing happened.

When to reach for one

Use a decision when the kernel is about to do something and the correct behaviour depends on a rule that is yours:

• Which warehouse should serve this order?
• Is this customer entitled to this price?
• Should this cart qualify for free shipping?
• Is this address serviceable?

Do not use a decision to react to something that already happened — that is an event. Deciding and reacting are different jobs, and using the wrong one is how a system ends up with race conditions it cannot name.

Why it is not a webhook

	Decision	Event
When	Before the kernel acts	After the change is committed
Shape	Declared question → declared answer	A fact, already true
Timing	Synchronous, inside the transaction	Asynchronous, at-least-once
If it fails	The command fails; nothing happened	Delivery is retried
Good for	Rules the outcome depends on	Reacting, syncing, notifying

The discipline it comes with

A decision runs inside a transaction, which means it holds one open. Two rules follow, and they are the kernel’s, not advice:

• Answer fast. A slow decision is a slow checkout, for every shopper, at the same time.
• Answer deterministically. The same question should get the same answer; the kernel may be asking on a path that has to be reproducible.

Where it fits

A decision is one of the four places customisation lives, and it is the one people find last, because it is the least common shape in this kind of system. It is usually the right answer when you were about to ask for a kernel change.

To write one, see the guide.