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

The one function that runs just before the store append.

# `prepare`

```elixir
@spec prepare(
  Decree.Application.t(),
  String.t(),
  [Decree.EventStore.EventData.t()],
  Decree.Aggregates.ExecutionContext.t()
) :: {:ok, [Decree.EventStore.EventData.t()]} | {:error, term()}
```

Answers a copy of `event_data` ready for the store.

Every framework append path reaches this one function, through `prepare_events/4`, with the
application's name and the stream's. Each event takes these steps, on copies:

  1. **Lookup.** One `Decree.PersonalFields.KeySource` lookup per subject, for each declared
     value that is not nil.

  2. **Resolve.** An unknown key fails the whole append. An erased one removes the value: a
     field becomes nil and a metadata key goes. A missing subject, a value that is already an
     envelope and metadata the application fences also stop here.

  3. **Tags.** `Decree.Event.Tags.tags/2`, followed by the framework's. An implementation
     sees the plaintext that will be stored, so an erased subject gets no tag derived from
     its value, and no tag holds ciphertext. Then the kinds the event requires, from
     `Decree.Event.RequiredTags.required/2`, on the same copy and the same tag context, so an
     erased value reads as absent. They go in `required_tag_kinds`, for the store to refuse.
     An event that requires kinds, on a command with no `command:` tag of its own, stops here
     with `{:error, :missing_required_tag}`, whatever tags the implementation answered.

  4. **Encrypt.** Declared fields and metadata entries become envelopes.

An event that declares nothing takes step 3 alone, and comes out as it went in, with tags.

It writes nothing, and `ExecutionContext.metadata` is untouched, so a `:wrong_expected_version`
retry derives afresh from plaintext. It runs once per attempt. A lookup aside, it is
deterministic: the same event and context give the same tags.

The first `{:error, reason}` stops and is returned. A raise from an implementation is not
rescued here: the aggregate or the decision answers it, having written nothing. On an event
with a declaration anything leaving an implementation can carry the value it failed on, so
its error reason, exit and throw are reduced by `Decree.PersonalFields.RedactedError.reduce/1`,
a throw leaving as the exit `{:nocatch, reduced}`, and a raise becomes a
`Decree.PersonalFields.RedactedError`. An event's `__required_tag_kinds__/2` is treated the
same way, because it sees the same plaintext.

## Framework tags

  - `command:<command_id>`, from the command's `command_id` field when that is a
    non-empty binary. There is no fallback, default or derived id: a command with none
    gets no `command:` tag.

  - `command_kind:<module>`, the command's module in `inspect/1` form. Always present.

  - `correlation:<key>`, from the command's `correlation_id` field when that is a
    non-empty binary. `ExecutionContext.correlation_id` is a different value, by default
    a fresh UUID per dispatch, and is never read.

  - `<kind>:<id>`, the stream's entity tag, when `ExecutionContext.aggregate_identity`,
    the identity the stream was routed by, is a lowercase canonical UUID
    (`Decree.UUID.canonical?/1`). It is never read from the command again, and never the
    prefixed stream name. See `Decree.Commands.Router.dispatch/2` for its kind.

The store removes a repeat, so a domain tag equal to a framework tag is stored once.

# `prepare_events`

```elixir
@spec prepare_events(
  Decree.Application.t(),
  String.t(),
  [struct()],
  Decree.Aggregates.ExecutionContext.t()
) :: {:ok, [Decree.EventStore.EventData.t()]} | {:error, term()}
```

Maps `events` to event data for the dispatch `context` describes, and answers them through
`prepare/4`. Every path that appends a command's events calls this one function, per stream.
No events prepare to `{:ok, []}`.

---

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