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
$allis 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.
Summary
Functions
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 :.
The tag every fact carries.
The fingerprint of a digest key: 16 lowercase hex characters. Raises an ArgumentError for
anything but a non-empty binary.
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.
The tag kinds no application tag may hold, and no family is.
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.
Types
Functions
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 :.
@spec fact_tag() :: String.t()
The tag every fact carries.
The fingerprint of a digest key: 16 lowercase hex characters. Raises an ArgumentError for
anything but a non-empty binary.
@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.
@spec reserved_kinds() :: [String.t()]
The tag kinds no application tag may hold, and no family is.
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.