# `Decree.Event.RequiredTags`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/event/required_tags.ex#L1)

The tag kinds an event may not be appended without.

A condition finds an event by its tags, so an event that should carry a tag and does not
is an event the condition misses, and nothing fails. An event opts in to having that
refused, in its own module, by exporting three functions:

    defmodule AddressChanged do
      @derive Jason.Encoder
      defstruct [:user_id, :address]

      def __required_tag_kinds__(%AddressChanged{address: nil}, _tag_context), do: []
      def __required_tag_kinds__(%AddressChanged{}, _tag_context), do: ["address"]

      def __conditional_tag_kinds__, do: ["address"]

      def __tag_kinds__, do: ["address"]
    end

  - `__required_tag_kinds__(event, tag_context)` answers the kinds this event must carry.
    It is called where `Decree.Event.Tags.tags/2` is, with the same plaintext and the same
    `Decree.Event.TagContext`, so an erased subject's dropped value reads as absent, and
    fails as `tags/2` fails, redactions included. Answering `{:error, reason}` fails the
    append, and anything else that is not a list fails it with
    `{:error, :invalid_required_tag_kinds}`.
  - `__conditional_tag_kinds__()` lists the kinds an event of this module can lack. A
    condition naming one requires nothing of itself: the tag is required when
    `__required_tag_kinds__/2` answers its kind, and only then. So a tag is present if and
    only if what it comes from is.
  - `__tag_kinds__()` lists every kind the module's `Decree.Event.Tags` implementation can
    produce. A kind that comes only from the route, as the stream's entity tag does, is
    listed here too, because a build check cannot know a route. Nothing reads it at runtime.
    `Decree.Decision.AppenderMap` does.

An event is opted in by exporting `__required_tag_kinds__/2`, and its list is `always/0`
followed by its answer. So a command with no usable `command_id` cannot append one, on any
route. The stream's entity tag is not among them: a stream whose id is not a UUID gets
none. Off a decision route or a rule's conditional append, an event without the export has
an empty list, and the store checks nothing for it.

The store refuses, before any statement: `{:error, :missing_required_tag}` for an event
lacking a kind on its list, and `{:error, :invalid_required_tag_kinds}` for a list that is
not kinds, an improper one included. A kind is carried by a tag equal to it, or by
`<kind>:<value>` with a value.

The `command` kind is carried by the framework's own tag and no other. A `Decree.Event.Tags`
implementation answering `command:forged` or a bare `command` does not satisfy it, so
`Decree.Event.Append.prepare/4` answers `{:error, :missing_required_tag}` for an opted-in
event on a command with no usable `command_id`, ahead of the store. Such a tag is not
dropped: one equal to the framework's is stored once. `command_kind` needs no such rule,
because the framework always writes it.

## On a decision

A decision's own append requires more, of every event it appends, opted in or not:
`always/0`, and the kinds of the tags on the condition's items naming the event's type, less
the module's `__conditional_tag_kinds__/0`. That takes kinds from what the items ask and from
nothing else, so a conditional kind `__required_tag_kinds__/2` answers stays required. See
step 8 of `Decree.Decision`. A create's fact item is left out: the decision never wrote it,
so a declared type on another member is not asked the route's kind. Every item the decision
wrote naming the type counts, so a kind only some events of a type carry, one member's stream
kind on a batch for example, belongs in that list.

A `Decree.Decision.Rule`'s conditional append requires the same, with no fact item to leave
out. See "Required tags" there.

That holds on those two appends and nowhere else. A plain aggregate appending a type a
decision queries has no condition to take kinds from, so it gets only what the event itself
answers. `Decree.Decision.AppenderMap` is what flags that aggregate.

# `always`

```elixir
@spec always() :: [String.t(), ...]
```

The kinds every opted-in event requires, and every event a decision or a rule's conditional
append appends.

# `conditional_kinds`

```elixir
@spec conditional_kinds(module()) :: [String.t()]
```

The kinds an event of this module can lack. None for a module without the export.

# `producible_kinds`

```elixir
@spec producible_kinds(module()) :: [String.t()]
```

The kinds an event of this module can carry: its `__tag_kinds__/0`, and `command`,
`command_kind` and `correlation`, which need no listing. Those three alone for a module
without the export.

# `required`

```elixir
@spec required(struct(), Decree.Event.TagContext.t()) ::
  {:ok, list()} | {:error, term()}
```

The kinds this event asks for itself: `always/0` and its answer, or none for an event without
the export. A decision's append and a rule's conditional one add to that, opted in or not. An answer that is not a list is `{:error, :invalid_required_tag_kinds}`, here. What
a list holds is the store's to check.

---

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