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

Finds the event types a decision's condition can miss.

A condition holds only if every event it should see carries the tags it looks for, and
only if whatever appends such an event is itself decided under a condition covering it. The
store can check neither from one append: a plain aggregate appending a queried type has no
condition to take kinds from. See `Decree.Event.RequiredTags`.

It is opt-in. Nothing in decree calls it, and it reads no router. An application calls it
from a build check of its own, with its rules and one map of who appends what:

    Decree.Decision.AppenderMap.verify!(
      [{{:decision, ClaimEmail}, ClaimEmail.query(fixture_command, fixture_context)}],
      %{EmailClaimed => [{ClaimEmailCommand, ClaimEmail}, {ImportUser, User}]},
      conditional: [ImportUser]
    )

`rules` is a list of `{key, items}`, `items` being every condition item of a fixture
dispatch: what `c:Decree.Decision.query/2` and any `c:Decree.Decision.followup_query/3`
answered, and on a create the fact item `[types: types, tags: [stream_tag]]` first. The
stream tag is the route's, and this reads no router, so the application passes that item:

    {{:decision, CreateClaim}, [[types: types, tags: ["claim:" <> fixture_id]] | query_items]}

**Keys.** A key says what its module is, and nothing finds that out another way: not loading
the module, its exports, its name or the order things compile in.

  - `{:decision, module}`: a `Decree.Decision`. Its `__decision__/0` is called for its
    `create:` types, so a module that is no decision raises. It covers every row whose
    target is the module, and another rule's rows as below.
  - `{:rule, module}`: a `Decree.Decision.Rule`. Its `__rule__/0` is called, so a module that
    is no rule raises. It is no create and covers no row: the commands its route decides go
    in `conditional:`.
  - `{:aggregate, module}`: nothing is called. Its items are checked as any rule's are, and it
    covers no row, its own commands' included.

Any other key, a bare module included, raises `ArgumentError` naming it, before any problem
is computed. Problems name the module, not the key.

`appenders` maps each event module to its `{command_module, target_module}` rows. The
options:

  - `conditional:` command modules an aggregate decides under the rule's condition.
  - `dominant:` `{event_module, command_module}` pairs, the exceptions named by hand.

**Fact item.** `c:Decree.Decision.query/2` may answer `[]` on a create, so a rule without
the fact item names none of what the create reads. For a decision declaring `create:`, the
rule's first item must name exactly the declared types, in any order, and exactly one tag,
as it is first at a dispatch. An item further down does not count. Otherwise the problem is
`{:no_fact_item, decision}`, ahead of the rule's other problems. Only a `:decision` key is
ever a create.

Then, for each rule, for each type its items name, it checks two things.

**Tag coverage.** Each tag's kind on an item naming the type must be one the module can
produce, by `Decree.Event.RequiredTags.producible_kinds/1`. Otherwise the problem is
`{:missing_tag_kind, type, kind, decision}`. A conditional kind counts for nothing here: an
event that may lack a kind must still be able to carry it.

**Condition coverage.** A type with no row is `{:no_appender_row, type, decision}`. Every
row's target must be the rule's own `:decision` key, or another `:decision` key whose items
name that type with at least these kinds, or its command must be in `conditional:`, or the
pair in `dominant:`. Every rule of that other decision naming the type must, because each
stands for a dispatch appending it, and a rule not naming it says nothing. Otherwise the
problem is `{:unchecked_appender, type, command, target, decision}`. A rule's fact item
covers nothing for another rule, because a dispatch asks no event for its kinds.

A type that names no event module is `{:unknown_type, type, decision}`.

**A declared aggregate's rule.** A `Decree.Decision.Rule` goes in `rules` under a `:rule`
key, `{{:rule, EmailRule}, items}`, with the row `{command, aggregate}` and each command the
rule's route decides in `conditional:`. An aggregate key, `{{:aggregate, User}, items}`,
certifies none of its own commands: each still needs `conditional:` or `dominant:`.

# `appenders`

```elixir
@type appenders() :: %{
  required(module()) =&gt; [{command :: module(), target :: module()}]
}
```

# `option`

```elixir
@type option() :: {:conditional, [module()]} | {:dominant, [{module(), module()}]}
```

# `problem`

```elixir
@type problem() ::
  {:missing_tag_kind, type :: String.t(), kind :: String.t(),
   decision :: module()}
  | {:no_appender_row, type :: String.t(), decision :: module()}
  | {:unchecked_appender, type :: String.t(), command :: module(),
     target :: module(), decision :: module()}
  | {:unknown_type, type :: String.t(), decision :: module()}
  | {:no_fact_item, decision :: module()}
```

# `role`

```elixir
@type role() :: :decision | :rule | :aggregate
```

# `rule`

```elixir
@type rule() :: {{role(), module()}, items :: [keyword() | map()]}
```

# `check`

```elixir
@spec check([rule()], appenders(), [option()]) :: [problem()]
```

Answers the problems, by rule and by type, in the order given.

Raises `ArgumentError` naming the first key that is not `{:decision, module}`,
`{:rule, module}` or `{:aggregate, module}`, before any problem is computed.

# `verify!`

```elixir
@spec verify!([rule()], appenders(), [option()]) :: :ok
```

Answers `:ok` when there are no problems, and raises `ArgumentError` naming every one.

---

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