# `Decree.Decision.Rule`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/decision/rule.ex#L1)

What an aggregate's append has to check beyond its own stream.

An aggregate decides over its stream, and a rule such as one holder per address spans many.
A rule names what to read. The aggregate reads it for one command, `execute/2` sees what the
read answered, and the append goes in on the aggregate's own stream under a condition: it
fails if anything the rule read about has appeared since. The aggregate keeps its process,
its stream, its expected version and its state.

    defmodule EmailRule do
      use Decree.Decision.Rule

      def query(%RegisterUser{digest: nil}, _tag_context), do: []

      def query(%RegisterUser{digest: digest}, _tag_context) do
        [[types: ["Elixir.UserRegistered"], tags: ["email:" <> digest]]]
      end

      def followup_query(%RegisterUser{}, _tag_context, registrations) do
        for %UserRegistered{user_id: user_id} <- registrations do
          [types: ["Elixir.UserErased"], tags: ["user:" <> user_id]]
        end
      end
    end

A route names the rule, and the command names a place for what the read answers:

    defmodule RegisterUser do
      defstruct [:command_id, :user_id, :digest, :rule_result]
    end

    dispatch RegisterUser, to: User, identity: :user_id, rule: EmailRule

    def execute(%User{}, %RegisterUser{rule_result: %Result{events: events}} = command) do
      case holders(events) do
        [] -> %UserRegistered{user_id: command.user_id, digest: command.digest}
        [_holder | _] -> {:error, :email_taken}
      end
    end

The route is per command, so the aggregate's other commands stay plain. See "Two
declarations" for the store's half.

## Callbacks

  - `c:query/2` names what to read: a list of items, `[]` for nothing to check, or
    `{:error, reason}`.
  - `c:followup_query/3`, optional, names a second read that depends on what the first
    found: a list of items, `[]` to skip it, or `{:error, reason}`.
  - `c:index_families/0`, optional, says which tag kinds hold digests. See "Required tags".

Items are those of `Decree.Decision`, with two differences. `replay: true` answers
`{:error, :invalid_query}`, because a rule has no scope to hold one to. And a rule's item may
name `key:`, any term, once: it says which item matched an event (see "What rides"). A second
`key:` in one item answers `{:error, :invalid_query}`, with no statement. Both callbacks may run
several times for one dispatch, so they must have no side effects. They run in the aggregate's
process and hold up its mailbox, as a rebuild does.

The build fails on anything a rule does not have: `evolve/2`, `decide/2`, `admit/2`,
`scope_tags/1`, `initial_state/0`, `command_window_ms/0`, `handle/2`, `create:` and
`activation:`.

## What a dispatch does

In the aggregate's process, after `before_execute`, on each attempt:

  1. Call `c:query/2`. Its error is the answer. Refuse an item naming no types, a
     `replay: true` item, and more items or probes than the bounds allow. Read the items
     with the index item. `[]` skips to step 4 with no statement and no index check, and
     step 5 is then the batch bound and a plain append.
  2. Call `c:followup_query/3` if it is defined, with the events the first read matched, those
     the rule lists decrypted. Check both bounds again across both reads, read the items
     with the index item, and merge by position. The first read's `after` stands for both.
     More matched events than `max_events`, both reads together, refuses.
  3. Check the index as "Index facts" in `Decree.Decision` says, on the facts' tags the reads
     returned, with no `command` requirement: a family the rule's items require with no
     enabled index answers `{:error, :tag_index_not_enabled}`, before `execute/2`. Keep the
     events the rule's own items matched, and decrypt the ones it lists.
  4. Call `execute/2` with those events on a local copy of the command. Everything
     after that is the aggregate's as on any other route: `apply/2`, preparing, tags.
  5. Refuse more new events than `max_batch_events`, compare the digests and require the
     tags, as "Required tags" says, and append at the expected version under the condition.
     Its items are the rule's own from both reads and the index item, and its `after` is the
     first read's: the store's head at that read, and never 0 on an empty store. After `[]`
     there is no condition: past the bound, the append is the one a route with no rule makes,
     with no digest comparison and no required tags but the event's own.

So an event committed after the first read, the gap between the two reads included, fails
the append if it matches. An `after` taken from the second read would miss what landed in
that gap.

Fold, `admit/2`, classification, the command window and scope checks do not run: those are a
decision's. A rule's reads have no command item, and an aggregate keeps its own "already
exists" guard, so a `command_id` reused across two streams behaves as it does on any
aggregate route. On an aggregate that declares a command window, the command item joins the
rule's items in the same read and condition, and the window classifies: see "Command window"
in `Decree.Aggregate`. A `[]` from `c:query/2` there still reads the window. A rule reads through a decision's path, with its compiled bounds, so a query
naming something deletable answers `{:error, :query_names_deletable}`.

## What rides

`execute/2` stays pure and of arity 2. The command is its only added input, because what a
read answers is never aggregate state.

The command's `:rule_result` field holds a `Decree.Decision.Rule.Result`, its `events` being
the data of the events the rule's own items matched, both reads', in position order. A caller's
value there is overwritten. A route with no rule leaves the field as sent.

Its `matched_keys` is parallel to `events`: for each event, the keys of the rule's own items
that matched it, each once, in item order, the first read's before the follow-up's. An item
with no `key:` adds none, so an event only unkeyed items matched has `[]`. A key never reaches
the store, the condition or telemetry: it is taken off the item before the read. So a key may
name an id. `c:followup_query/3` gets the first read's events alone, with no keys.

It is set on a copy, for one call. `Decree.Aggregates.ExecutionContext` keeps the plain
command, so nothing the framework does after the call holds a read: no reply, no metadata, no
state, no snapshot. `execute/2` is the application's own code, and the framework does not
look inside what it returns. So it must not copy the result, or anything in it, into an
event, or into the state it seeds a `Decree.Aggregate.Multi` with: either would keep it.
`Inspect` shows nothing of a result. With the JSON serializer, an event whose encoder hands a
result to `Jason` raises before it is stored. An encoder of the event's own can leave the
field out or unpack its events, and another serializer has no such fence at all.

**`[]`** from `c:query/2` means this command has nothing to check, as a registration with no
address has not. `execute/2` gets an empty result, and the append is the plain one a route
with no rule makes, once the batch is within `max_batch_events`. A decision refuses `[]`,
because a decision that reads nothing has nothing to decide on, and a rule decides nothing.

## Required tags

A condition finds an event by its tags, so a rule's conditional append requires of every event
what a decision's does, through the same code, opted in or not: `always/0` of
`Decree.Event.RequiredTags`, the kinds of the tags on the condition's items naming the event's
type, less the module's `__conditional_tag_kinds__/0`, and the event's own answer. All the
condition's items count, since a rule has no fact item. So a kind a query names is required
here though the same event on a plain route is not refused, and a command with no usable
`command_id` cannot append on a rule route.

`c:query/2` answering `[]` makes a plain append, with no condition to take kinds from, so an
event there gets its own answer only.

`c:index_families/0` works as "Digest tags" in `Decree.Decision` says, on the condition's items
from both reads, and fails the build on the same bad answers. The refusals are
`{:error, :missing_required_tag}` and `{:error, :digest_tag_mismatch}`, an atom with no digest
in it. Each answers with nothing appended, before any statement, and never retries.

## Retries

A failed condition runs the command again from `before_execute`, on the state the aggregate
has, and spends one of the attempts `retry_attempts` gives it. So does a lost expected
version, which rebuilds the state first, from a budget of its own: neither spends the other's,
and one dispatch runs `execute/2` at most `2 * retry_attempts + 1` times. Each attempt reads
afresh, with a fresh `after`. A condition spent answers `{:error, :too_many_attempts}`,
with the state unchanged, and never a success or a duplicate. `retry_attempts: 0` tries
once. An aggregate stopped under a dispatch restarts the dispatch, bounded by `retry_attempts`
as it is on any route, and the condition's budget starts again.

## Bounds

    use Decree.Decision.Rule, max_items: 8

`max_items`, `max_probes`, `max_events`, `max_batch_events` and `bound_reason:` are those of
"Bounds" in `Decree.Decision`, with the same defaults, the same rule for raising one, and the
same answers: `:decision_query_too_large` and `:decision_batch_too_large`. `max_items` counts
the index item, so 15 of a rule's own make 16, and `max_events` does not count the facts it
matches: they come by position, with no event (see "Index facts" in `Decree.Decision`).
`max_batch_events` holds on every append a rule route makes, a plain one after `[]` included.
A condition's items run under the `$all` lock on an aggregate route as on a decision's, so
lead each item with its narrowest tag.

## Leaks

A rule route is redacted whether or not the aggregate uses `Decree.PersonalFields.Aggregate`,
because a read can bring in another subject's plaintext. A raise from a callback, from
`execute/2`, `apply/2` or `before_execute`, from preparing, or from reading an event the rule
reads, in the store's deserializing, the mapping or an upcaster, reaches logs,
telemetry, `after_failure` and the answer as a
`Decree.PersonalFields.RedactedError` with a scrubbed stacktrace. An exit leaves reduced by
`Decree.PersonalFields.RedactedError.reduce/1`. A throw is reduced the same way and leaves as
an exit, `{:nocatch, reduced}`, because `gen_server` reads a term thrown from a callback as its
return, and a reduced `{:noreply, _}` is a valid one. Either takes the aggregate with it, and
the caller gets `{:error, :aggregate_execution_failed}`. An `{:error, reason}` from
`c:followup_query/3` is reduced the same way. `c:query/2` has read nothing, so its reason
stands.

None of these reaches the read's `[:decree, :event_store, :read_query]` span. The store's
deserializing and the mapping run inside it, and its exception event never fires:
a failure there stops it with `error` set to its kind alone, `:error`, `:exit` or `:throw`,
and is raised again after. The upcast runs after it stops. Each reaches the boundary above.

**An `{:error, reason}` from `execute/2` is not reduced.** It goes back to the caller, to
`after_failure` and to telemetry as it stands, as on any aggregate route. So `execute/2` answers
an atom or a tuple of its own, never a value it read.

An item's tag goes to the store and to telemetry as it is, so `c:followup_query/3` names an id
or a digest, never a value it decrypted.

## Personal fields

A rule lists the events it reads as a decision does:

    defmodule EmailRule do
      use Decree.Decision.Rule
      use Decree.PersonalFields.Aggregate

      @personal_fold [UserRegistered]
    end

A listed event reaches `c:followup_query/3` and `execute/2` with its body decrypted, and an
erased subject's field nil. An unlisted one reaches them as stored. One no key can read
answers `{:error, :key_unknown}`, with nothing appended, no retry, and the aggregate's state
still good. `@personal_state` and `@personal_state_subject` mean nothing on a rule.

## Two declarations

A route's `rule:` says which commands a rule covers. The store's `conditional_appends`
says which conditions it will run, because a condition takes time under `$all`:

    conditional_appends: [targets: [User]]

The condition's `target` is the route's aggregate module, and only `targets:` declares it: a
`stream_prefixes:` entry covering the aggregate's streams does not. The two must agree. An
application with a rule route checks them as it starts, right after its store has started,
against the config the running store parsed:

  - A rule route's aggregate with no store target raises an `ArgumentError`, naming both, and
    the application does not start: `start_link/1` answers
    `{:error, {:shutdown, {:failed_to_start_child, _id, _reason}}}`.
  - A store target no route declares logs a warning. It is not refused: a store can be
    shared, and a direct store caller may use a target.
  - A router outside the application is not checked at start, so a dispatch through it
    answers the store's `{:error, :undeclared_conditional_target}`, with nothing written,
    even when its streams start with a declared prefix.

An application with no rule route and no windowed aggregate checks nothing and asks its store
nothing, so a target its store declares draws no warning there. A windowed aggregate is a
target too: see "Command window" in `Decree.Aggregate`.

## What declaring leaves alone

A target is compared on a conditional append and nowhere else, and everything below goes by
a stream's prefix. So a declared aggregate's stream takes, exactly as before, plain appends
from its other commands, a hard delete of it and a snapshot of it. Hard deleting
such a stream removes what a rule reads there, which is a release: a rule must not hang
anything on those events staying.

The aggregate's own prefix should not be one of `conditional_appends`' `stream_prefixes`, which
would refuse its plain commands.

## The appender map

`Decree.Decision.AppenderMap` audits a rule as it does a decision. List it as
`{{:rule, EmailRule}, items}`, which is no create and covers no row, with the row
`{RegisterUser, User}` and each command its route decides in `conditional:`, here
`[RegisterUser]`. An `{:aggregate, User}` key has its items checked and certifies none of
its own commands, so it never stands in for `conditional:`.

## Telemetry

An aggregate's span runs as on any route. There is no `[:decree, :decision, :execute]` span,
and `[:decree, :decision, :read]`, `[:decree, :decision, :retry]` and
`[:decree, :decision, :refused]` are those of `Decree.Decision`, with `decision` being the rule:

  - `:read` fires once per attempt that read anything and passed the index check, and
    `fold_time` is what step 3 took after it.
  - `:retry` fires for `:append_condition_failed`, and on an aggregate that declares a command
    window also for `:new_command_match`, a command match only the rule's second read has. A
    lost expected version has no event of its own, on this route as on a plain one.
  - `attempt` counts every run of the command in this dispatch, for either reason.

A route with no rule fires none of them, unless its aggregate declares a command window, whose
read and retries fire `:read` and `:retry` with the aggregate's module as `decision`. The reads' `[:decree, :event_store, :read_query]`
span never fires its exception event, and its stop names a failure's kind in `error`: see
"Leaks".

# `item`

```elixir
@type item() :: Decree.Decision.item()
```

An item of `Decree.Decision`, which has what one may hold.

# `followup_query`
*optional* 

```elixir
@callback followup_query(command :: struct(), Decree.Event.TagContext.t(), [struct()]) ::
  [item()] | {:error, term()}
```

The items of a second read, given the events the first read's own items matched. `[]`
skips it.

# `index_families`
*optional* 

```elixir
@callback index_families() :: %{required(String.t()) =&gt; :digest | :plain}
```

Which tag kinds hold digests. See "Digest tags" in `Decree.Decision`. Defaults to none.

# `query`

```elixir
@callback query(command :: struct(), Decree.Event.TagContext.t()) ::
  [item()] | {:error, term()}
```

The items to read for a command, `[]` for nothing to check.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
