# `Decree.PersonalFields.Aggregate`
[🔗](https://github.com/sparkle-space/decree/blob/v0.1.0/lib/decree/personal_fields/aggregate.ex#L1)

What an aggregate reads of its personal fields.

    defmodule User do
      use Decree.PersonalFields.Aggregate

      @personal_fold [OAuthAccountLinked, PasskeyRegistered]
      @personal_state [oauth_links: :provider_uid, email: :self]
      @personal_state_subject :user_id

      defstruct [:user_id, :email, oauth_links: []]
    end

  - `@personal_fold` lists the events `apply/2` reads a declared or retired field of. They are
    decrypted in the fold, body fields only, because `apply/2` never sees metadata. Every other event
    reaches `apply/2` as stored, so an aggregate that folds a value it never reads is not
    locked by one subject's lost key. An event left off the list leaves an envelope in state.

  - `@personal_state` lists the state a snapshot must not hold in the clear. `state_field:
    entry_key` covers a field holding a list of maps with atom or string keys, and encrypts
    that key of each entry. `state_field: :self` covers a scalar, and encrypts the field's own
    value. `:self` is reserved, so it can't name an entry key. A value of any other shape under
    an `entry_key` records no snapshot. Those values are encrypted in the snapshot, and
    in-memory state stays plaintext.

  - `@personal_state_subject` is the state field that holds their subject.

It generates `__personal_fold__/0`, `__personal_state__/0` and `__personal_state_subject__/0`.
An aggregate without it pays one `function_exported?/3` per fold.

A list entry holding its key in both atom and string form records no snapshot.

An aggregate that uses this module can hold decrypted values in memory, from an event or from
a snapshot, whatever `@personal_fold` lists. So on every `apply/2`, listed event or not, and
on `execute/2` and `before_execute`, a raise reaches logs and telemetry as a
`Decree.PersonalFields.RedactedError`, and an exit or a throw leaves reduced by
`Decree.PersonalFields.RedactedError.reduce/1`. A throw leaves as an exit, `{:nocatch, reduced}`,
never as what a `gen_server` callback returned: a reduced `{:noreply, _}` would otherwise keep
the aggregate running on a state of `:redacted`. The aggregate stops, and a caller waiting on a
command gets `{:error, :aggregate_execution_failed}`. An aggregate that doesn't use it is
untouched, except that a throw from a `Decree.Event.Tags` implementation on an event with a
declaration leaves the same way on any aggregate: see `Decree.Event.Append.prepare/4`.

A `Decree.Decision` uses this module too, for what `evolve/2` and `followup_query/3` read:
`@personal_fold` means there what it means here, and a raise from a decision that uses it is
redacted the same way. `@personal_state` and `@personal_state_subject` don't apply, because a
decision has no snapshot. See "Personal fields" in `Decree.Decision`.

A `Decree.Decision.Rule` uses it for what `followup_query/3` and `execute/2` read, the same
way. Using it or not changes nothing about a rule route's raises, which are always redacted.
See "Leaks" there.

---

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