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

The grammar of the facts that say whether a tag index can be trusted.

A condition finds an event by its tags, so a decision rests on the tag rows being complete.
Whether they are is a fact on the ledger, in events the application appends. Decree ships no
such event and no command: it ships the grammar, the store's guard on it, and the check a
decision runs over it.

## The grammar

A fact is an event carrying `fact_tag/0`, `"tag_index:fact"`, and at least one state tag:

    tag_index_state:<family>:<key or ->:<enabled|disabled>

`state_tag/3` builds one. `<family>` is a tag kind and `<key>` a fingerprint, or `-` for a
family with no key. The store refuses an append, with `{:error, :invalid_tag_index_fact}`
and before any statement, when an event carries a `tag_index` tag that is not exactly
`tag_index:fact`, a `tag_index_state` tag that does not parse, or one of the two without
the other. A disable with no fact tag would be invisible to the read that finds the facts,
so an earlier enable would stand.

`tag_index` and `tag_index_state` are `reserved_kinds/0`. Neither can be declared deletable,
and `delete_stream_tags` refuses them, because a fact whose state tag is gone could have
been a disable.

## The families

A tag of a kind in `named_families/0` is in the family of that kind, and so is a tag of a
kind a decision lists in its `index_families/0`. Any other kind is in the `entity` family.
Decree's own named families are `command`, `command_kind` and `correlation`; the
application adds its own kinds through the application environment:

    config :decree, :tag_index_named_families, ["tenant_slug", "plan_slug"]

Every node must run the same list for the store's life. The list decides which facts a
decision requires, so changing it changes what an existing fact covers, and a kind left out
falls into the `entity` family without a word.

A kind listed `:digest` holds `<fingerprint>:<digest>`, and its family's key is that
fingerprint: `digest_key/1` reads it. Every other family has no key.

## The fold

A decision reads the facts in its own read and folds them in position order: the last
state per family and key wins, and a family and key with no fact is disabled. A fact the
fold cannot attribute, one whose state tags are gone, refuses as a disable would. See
"Index facts" in `Decree.Decision`.

## The fingerprint

`fingerprint/1` is DOC-1's form: the first 8 bytes of HMAC-SHA-256 keyed by the key material
over `"tag-digest-fingerprint"`, in lowercase hex, 16 characters. It is derived from the key
material and shows nothing about the key, and it holds no `:`, so it reads back from a
`<fingerprint>:<digest>` value. It names a digest key without holding it, so one key's tags
and its retirement meet under one name. The key and the digests stay the application's.

## The lifecycle

  - **A fresh store.** The application's release step appends the enabling batch only when
    `$all` is empty, so the facts sit from position 1 and every later event is covered by
    them.
  - **A store with history.** The same step does nothing, and every decision refuses
    `{:error, :tag_index_not_enabled}` until a family is repaired and enabled.
  - **Repair.** A disable for repair, the repair writing the tag rows, then an enable under
    a new index id. That is the supported way to retag. There is no shadow index to build
    beside the live one.
  - **Retirement.** A disable for a family and fingerprint whose key is retired. A key
    restored later has the same material, so the same fingerprint, and meets that disable.
  - **Never deleted.** A hard delete of a stream holding a fact, its own or through a link
    row written before links were removed, answers `{:error, :hard_delete_of_index_fact}`.
    A hard delete takes the stream's events from every stream, so a disable gone that way
    would leave an earlier enable standing. A fact stays for the store's life.

# `family`

```elixir
@type family() :: String.t()
```

# `key`

```elixir
@type key() :: String.t() | nil
```

# `state`

```elixir
@type state() :: :enabled | :disabled
```

# `digest_key`

```elixir
@spec digest_key(term()) :: {:ok, String.t()} | :error
```

The fingerprint a digest tag's value names, `{:ok, fingerprint}` for `<fingerprint>:<digest>`,
or `:error`. The value is what follows the tag's kind and its `:`.

# `fact_tag`

```elixir
@spec fact_tag() :: String.t()
```

The tag every fact carries.

# `fingerprint`

```elixir
@spec fingerprint(binary()) :: String.t()
```

The fingerprint of a digest key: 16 lowercase hex characters. Raises an `ArgumentError` for
anything but a non-empty binary.

# `named_families`

```elixir
@spec named_families() :: [family()]
```

The families that are their own kind's, whatever a decision lists: decree's own `command`,
`command_kind` and `correlation`, then the application's `:tag_index_named_families`, in
order. Raises an `ArgumentError` when that is not a list of tag kinds that are not reserved.

# `reserved_kinds`

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

The tag kinds no application tag may hold, and no family is.

# `state_tag`

```elixir
@spec state_tag(family(), key(), state()) :: String.t()
```

A fact's state tag. `key` is nil for a family with no key. Raises an `ArgumentError` for a
family that is not a tag kind or is reserved, a key that is empty, holds a `:` or is `-`, and
a state other than `:enabled` and `:disabled`.

---

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