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

Personal fields: values encrypted under their subject's key before they reach the store.

An event declares its personal fields and metadata entries, and whose they are, through
`Decree.Event.PersonalFields`. An application names where keys come from with `key_source:`
on `use Decree.Application` (see `Decree.PersonalFields.KeySource`). Nothing else is needed,
and an application or an event that declares nothing is unchanged.

The store only ever sees JSON: everything here runs in the framework.

## What each path does

  - **Append.** `Decree.Event.Append.prepare/4` looks up each subject of each event, drops
    erased values, takes the tags from the plaintext that will be stored, then encrypts. A
    retired slot takes no lookup and is stored as given, and an envelope in one fails the
    append with `{:error, :personal_field_is_envelope}`. A metadata key the application
    lists in `personal_metadata_keys:` passes only when the event declares it under
    `personal_metadata:`; retiring it is not enough. An aggregate's append runs `prepare/4`,
    and a decision's, once per member with that member's stream.
    `Decree.EventStore.append_to_stream/5` and `Decree.Store` do not: an application's own
    direct append of a declared event stores what it is given, so a build check of its own
    must fence that.

  - **Delivery.** `Decree.Event.Handler` decrypts an event for a handler whose `handle/2`
    names it in a clause head, and for no other, retired slots included. The
    `RecordedEvent` is never rewritten.

  - **Rehydration.** An aggregate lists the events its state reads with
    `Decree.PersonalFields.Aggregate`, and those are decrypted in its fold.

  - **Decisions.** A `Decree.Decision` lists the events it reads the same way, and those
    reach `evolve/2` and `followup_query/3` decrypted, body only. Every other event reaches
    them as stored. There is no snapshot.

  - **Rules.** A `Decree.Decision.Rule` lists the events it reads the same way, and those
    reach `followup_query/3` and `execute/2` decrypted, body only. See "Personal fields" there.

  - **Snapshots.** The state an aggregate lists is encrypted on the way to the store and
    decrypted on the way back.

  - **Stream reads.** A bare read answers ciphertext. A reader that needs plaintext calls
    `decrypt_recorded_event/2`.

  - **Upcasters** run first, and see ciphertext. One may pass an envelope on, or move it to
    another struct. It can't read it, or move it to another field. The declaration read is
    the upcast struct's: a slot it neither declares nor retires reaches a reader as stored.

Every read path walks an event's retired slots after its declared ones, the same way.

## Three answers

A lookup answers a key, `:erased` or `:unknown`. Erased means absent: a field is nil and a
metadata key is gone. Unknown is everything else, and it is never written or read as absent:
an append fails with `{:error, :key_unknown}`, a delivery is held and not acked, an
aggregate stops rather than fold a missing value, and a decision answers
`{:error, :key_unknown}` with nothing appended. See `Decree.Event.Handler`,
`Decree.Aggregates.Aggregate` and `Decree.Decision`.

A nil stays nil. A bare value in a declared field passes through, and emits
`[:decree, :personal_field, :plaintext_read]` unless its subject is `{:when_present, _}`. A
bare value in a retired slot passes through with no lookup and emits nothing.

## Telemetry

  - `[:decree, :personal_field, :key_unknown]`, with `%{application:, subject_id:}`, for a
    lookup that answered unknown and for a value that a key could not read. `subject_id` is
    nil for a malformed envelope or a subject that is not an id.

  - `[:decree, :personal_field, :plaintext_read]`, with `%{application:, event_type:, field:}`
    and no value.

# `answers`

```elixir
@type answers() :: %{
  optional(term()) =&gt; {:ok, String.t(), binary()} | :erased | :unknown
}
```

# `decrypt_recorded_event`

```elixir
@spec decrypt_recorded_event(
  Decree.Application.t(),
  Decree.EventStore.RecordedEvent.t()
) ::
  {:ok, Decree.EventStore.RecordedEvent.t()} | {:error, :key_unknown}
```

Decrypts a recorded event for a reader that needs plaintext.

Answers `{:ok, event}`, with its fields and metadata decrypted, erased fields nil and erased
metadata keys removed, or `{:error, :key_unknown}` if any value can't be read. An event that
declares nothing comes back as it is.

The declaration read is the one of the struct after upcasting, and the subject is each
envelope's own, so a conditional declaration is not worked out again.

---

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