decree

An event-sourcing toolkit for Elixir: a Postgres event store (Decree.Store) and a CQRS framework (Decree) on top of it, with decision rules: conditions an append checks across streams, such as "one account per handle".

decree is built for sparkle.space and for the projects sparkle.space produces. That is its first purpose. If it is useful to you too, you are welcome to use it, and we hold it to the same standard either way.

Status

decree is pre-1.0 (version 0.1.0). Until 1.0, a minor version (0.2.0) may change the API or the store schema; a patch version (0.1.1) does neither. CHANGELOG.md records each release and how to upgrade, and a commit on main between releases promises nothing.

It has one production user, sparkle.space. What that use proves, and what it does not:

Installation

Add decree from Hex, with Jason for the JSON serializer:

# mix.exs
defp deps do
  [
    {:decree, "~> 0.1.0"},
    {:jason, "~> 1.4"}
  ]
end

~> 0.1.0 takes patch versions only, since a minor version may break (Status). To format the router's dispatch and identify without parentheses, add :decree to import_deps in your .formatter.exs.

Compatibility

decree needs Elixir 1.20 or later. CI tests one combination: Elixir 1.20.4 on Erlang/OTP 29.1.2, against PostgreSQL 18. Other versions of Erlang/OTP and PostgreSQL are not tested.

A minimal application

One aggregate with a decision rule, a router, an application and an event handler. An account claims a handle, and the rule refuses a handle another account holds. The test test/framework/readme_example_test.exs compiles and runs the three blocks below from this file.

# config/config.exs
import Config

config :my_app, event_stores: [MyApp.EventStore]

config :my_app, MyApp.EventStore,
  serializer: Decree.Serialization.JsonSerializer,
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  database: "my_app_eventstore",
  conditional_appends: [targets: [MyApp.Account]]

config :my_app, MyApp.App,
  event_store: [event_store: MyApp.EventStore],
  registry: :local
# lib/my_app.ex
defmodule MyApp.EventStore do
  use Decree.Store, otp_app: :my_app
end

defmodule MyApp.RegisterAccount do
  use Decree.Command

  defstruct [:command_id, :account_id, :handle, :rule_result]
end

defmodule MyApp.AccountRegistered do
  @derive Jason.Encoder
  defstruct [:account_id, :handle]

  defimpl Decree.Event.Tags do
    def tags(%{handle: handle}, _context), do: {:ok, ["handle:" <> handle]}
  end
end

defmodule MyApp.UniqueHandle do
  use Decree.Decision.Rule

  @impl Decree.Decision.Rule
  def query(%MyApp.RegisterAccount{handle: handle}, _tag_context) do
    [[types: ["Elixir.MyApp.AccountRegistered"], tags: ["handle:" <> handle]]]
  end
end

defmodule MyApp.Account do
  alias Decree.Decision.Rule.Result
  alias MyApp.{AccountRegistered, RegisterAccount}

  defstruct [:account_id, :handle]

  def execute(
        %__MODULE__{account_id: nil},
        %RegisterAccount{rule_result: %Result{events: []}} = command
      ) do
    %AccountRegistered{account_id: command.account_id, handle: command.handle}
  end

  def execute(%__MODULE__{account_id: nil}, %RegisterAccount{}), do: {:error, :handle_taken}
  def execute(%__MODULE__{}, %RegisterAccount{}), do: {:error, :already_registered}

  def apply(%__MODULE__{} = account, %AccountRegistered{} = event) do
    %__MODULE__{account | account_id: event.account_id, handle: event.handle}
  end
end

defmodule MyApp.EnableTagIndex do
  use Decree.Command

  defstruct [:command_id, :ledger_id, :family]
end

defmodule MyApp.TagIndexEnabled do
  @derive Jason.Encoder
  defstruct [:family]

  defimpl Decree.Event.Tags do
    alias Decree.Store.TagIndex

    def tags(%{family: family}, _context) do
      {:ok, [TagIndex.fact_tag(), TagIndex.state_tag(family, nil, :enabled)]}
    end
  end
end

defmodule MyApp.TagIndexLedger do
  defstruct []

  def execute(%__MODULE__{}, %MyApp.EnableTagIndex{family: family}) do
    %MyApp.TagIndexEnabled{family: family}
  end

  def apply(%__MODULE__{} = ledger, %MyApp.TagIndexEnabled{}), do: ledger
end

defmodule MyApp.Router do
  use Decree.Commands.Router

  identify MyApp.Account, by: :account_id, prefix: "account-"
  identify MyApp.TagIndexLedger, by: :ledger_id, prefix: "tag-index-"

  dispatch MyApp.RegisterAccount, to: MyApp.Account, rule: MyApp.UniqueHandle
  dispatch MyApp.EnableTagIndex, to: MyApp.TagIndexLedger
end

defmodule MyApp.App do
  use Decree.Application, otp_app: :my_app

  router MyApp.Router
end

defmodule MyApp.Welcome do
  use Decree.Event.Handler, application: MyApp.App, name: "welcome"

  require Logger

  def handle(%MyApp.AccountRegistered{handle: handle}, _metadata) do
    Logger.info("welcome, @" <> handle)
  end
end

Create the store's database and tables, then start MyApp.App and MyApp.Welcome under your application's supervisor:

mix decree.store.create
mix decree.store.init
# On a fresh store, before anything else is appended
:ok =
  MyApp.App.dispatch(%MyApp.EnableTagIndex{
    command_id: Decree.UUID.uuid4(),
    ledger_id: Decree.UUID.uuid4(),
    family: "entity"
  })

register = fn handle ->
  MyApp.App.dispatch(%MyApp.RegisterAccount{
    command_id: Decree.UUID.uuid4(),
    account_id: Decree.UUID.uuid4(),
    handle: handle
  })
end

:ok = register.("ada")
{:error, :handle_taken} = register.("ada")
:ok = register.("grace")

MyApp.Welcome logs "welcome, @ada" and "welcome, @grace".

Every command carries a command_id, a lowercase canonical UUID its sender mints: a dispatch refuses a command without one (Decree.Command). What the rule route needs, beyond a plain one:

Decree.Decision.Rule covers the rest: a follow-up query, keys, bounds, retries and the required tags.

Layers

One OTP application, :decree, in two layers:

mix decree.verify.eventless --router MyApp.Router fails on any routed handler arm that can accept a command without appending an event: an aggregate handler answering [], nil, :ok, {:ok, []} or {:ok, nil}, which the aggregate accepts with no events, and a decision's decide/2 answering those or {:streams, []}, which a dispatch refuses at runtime. It reads each router's registry (__route__/1 names every routed module and function), walks their source under the project's elixirc_paths without compiling or loading it, and reports what it cannot classify as a finding too. It has no allow-list and no waiver; --router repeats, and --no-compile skips mix compile. Decree.Verify.Eventless documents the shapes, what the walk follows and its stated residuals.

Being one OTP application, the store's supervision tree (the supervisor registered as Decree.Store.Supervisor, started by Decree.Store.Application) is a child of Decree.Supervisor and shares its restart budget. Upstream, :eventstore was a separate application that stopped on its own when its supervisor exhausted its restart budget; in decree the failure escalates to Decree.Supervisor, and exhausting that budget stops :decree. The children, their names and their order are upstream's.

The store never references the framework. scripts/check_layers.exs enforces this from the compiled BEAM files and CI runs it:

mix run --no-start scripts/check_layers.exs

What is absent, on purpose:

Running the tests

The suites need a Postgres server (stock Postgres 18). Host, port and credentials come from the environment, defaulting to localhost:5432, user and password postgres:

export DECREE_PG_HOST=127.0.0.1 DECREE_PG_PORT=5432   # DECREE_PG_USER, DECREE_PG_PASSWORD
mise install
mix deps.get
mix test

CI runs the same suites on stock Postgres, with no durability options. Turning off fsync, synchronous_commit and full_page_writes on CI's Linux runners was measured on 2026-10-29: six runs of each averaged 117.5 s stock and 118.0 s tuned. That is no gain, so the options were not kept. Almost all of the suite's time is synchronous tests, not flushes.

The test alias creates and initialises every test event store (decree.store.create, decree.store.init) and the projections repo's database (ecto.create), then runs four suites in one VM:

Suite Path Covers
framework test/framework Commanded's suite, on the Postgres store: applications, routing, dispatch, aggregates, snapshots, event handlers, middleware, upcasting, telemetry
store test/store EventStore's suite: storage, streams, subscriptions, notifications, advisory locks, schemas, config
conformance test/conformance the store conformance suite (below)
projections test/projections Commanded Ecto projections: projection versions, schema prefixes, error and after-update callbacks

Framework and projections tests run their applications on Decree.FrameworkEventStore (or a test store that wraps it) over the decree_framework_test database; Decree.PostgresCase empties it before each test. Tests tagged :migration (they restore old database dumps with pg_restore and compare schemas with pg_dump), :manual, :ignore and :distributed are excluded. CI installs the Postgres 18 client and runs mix test --include migration; run the same locally when a Postgres 18 pg_restore and pg_dump are on PATH. DROPPED_TESTS.md lists every upstream test not carried over, and why.

The conformance suite

test/conformance runs Commanded's shared event store test cases (test/framework/event_store/support/*_test_case.ex) through the Decree.EventStore facade of a started application, against its Decree.Store module on Postgres. It is the conformance suite for the one store implementation, and covers:

Formatting and compile checks

mix format --check-formatted
mix compile --warnings-as-errors

Decree.Store.Subscriptions.GeneratedFsm wraps the fsm dependency's use Fsm, marking its expansion as generated code so Elixir 1.20's type checker does not report warnings from the dependency's macro against decree.

Dependency audit

CI's Deps Audit job fails the build on either check:

mix hex.audit
mix deps.audit

mix hex.audit reports retired Hex packages and, from Hex 2.5, packages with security advisories. mix deps.audit (mix_audit, a dev and test dependency) checks mix.lock against its own advisory list. The two lists differ, so CI runs both. mix_audit ignores a failed clone of its advisory repository and then reports no vulnerabilities, so the CI step also fails when the clone left no advisories. Neither audit scans a git dependency; UPSTREAM.md (Dependency pins) lists those.

Provenance and licence

decree is derived from Commanded, EventStore, Commanded EventStore Adapter and Commanded Ecto Projections, all by Ben Smith under the MIT License. It copies the code sparkle.space uses, with no fork and no upstream history, and has changed it since.

Issue references such as sparkle-space/sparklespace#N in the code, the docs and the commit history point at sparkle.space's own tracker, which is private.

Contributing and security

Issues are welcome. Pull requests are by arrangement while decree is pre-1.0: see CONTRIBUTING.md. Report a vulnerability privately, as SECURITY.md describes.