The encryption context: the canonical vocabulary, the four-layer composition, and the bounds the engine does not check.

The context is a flat map of String.t() to String.t() that rides every message in the clear and is covered by the header authentication tag. Two properties follow, and both are load-bearing:

• every pair is public to anyone holding a ciphertext, so putting a key in the context is a disclosure decision, and
• no pair can be edited without breaking the tag, which is what binds a message to the row, column and scope it was written for.

This module owns the vocabulary and the composition. It does not enforce the required set - that is the vault's :required_context plus the required-context CMM (ADR-0004 decisions 3 and 5) - and it does not compare a reproduced context against a stored one, which is the decrypt path's (decision 6).

The canonical vocabulary

Six host-facing keys, spelled bare and in snake_case, and two reserved prefixes. canonical_keys/0 and reserved_prefixes/0 are the one place the strings live, so a sibling package matches against this module rather than against a copy of a literal.

The vocabulary is open at the edges and closed in the middle: a host adds its own keys freely, and it may neither redefine one of the six nor write under aws-crypto- (the engine's, and it may grow) or encryptor- (this package's). Adding a key to the table above is an ADR, not a call site.

scope_ref is a pinned v2 wire constant: it is written into every message's authenticated context, so respelling it again would leave every stored message unreadable (ADR-0009 Amendment A, A1 row 1). scope_ref_key/0 returns it. Its retired v1 spelling, tenant_ref, is not in the vocabulary and stays reserved (A4).

The four layers

compose/3 merges them, lowest precedence first, and refuses rather than silently overriding:

The refusals, in the order they are checked:

• a non-string, empty, or non-UTF-8 key or value is {:invalid_context_value, key}, before the engine is called - the engine's serializer would otherwise either raise deep inside a Format module or accept something whose serialization a reader cannot reproduce;
• a per-call or static key that is reserved, or that collides with a vault-supplied or package-reserved key, is {:reserved_context_key, key};
• a per-call key that collides with a static key at a different value is {:encryption_context_conflict, key}. The same value is not a conflict, so a call site that spells out what configuration already says is redundant rather than broken.

On a :scoped vault the scope pair is the vault's alone: scope_ref, scope_id and tenant_id are all refused from a caller, because :key is the whole of per-scope routing and a scope named twice is a scope that can disagree with itself. tenant_id stays refused beside scope_id because a host that followed earlier docs may still send it (ADR-0009 decision 3). scope_ref is refused on a :single vault too, where there is no scope to name at all. The retired v1 spelling tenant_ref is refused on both profiles, so a caller cannot put a pair spelled like the v1 scope reference into a context (ADR-0009 Amendment A, A4).

The bounds

The engine performs no size validation, and the context is written into every message, so its serialized size is a per-row storage cost paid forever. This module refuses, per call:

• more than 32 pairs, as {:invalid_context_value, :count},
• a serialized context over 4 KiB, as {:invalid_context_value, :too_large},
• a key or value that is empty or not valid UTF-8.

The static half is bounded once, at start, by Encryptor.Vault.Config, which reads its numbers from max_pairs/0 and max_bytes/0 here. The numbers are conservative and are stated rather than measured (ADR-0004 open question 4).

Nothing that varies per row may go in the context

A primary key, a row id, a timestamp, a request id, or a user id does not belong in a context. This is a correctness-adjacent rule rather than a style preference: the serialized context is hashed into the materials cache id, so each distinct context is its own cache entry. The provider round trip behind it - a key-store read plus a root-vault decrypt - is paid on every call in any case, per row, forever.

table and column are per-column, which is bounded by the schema. A host with 200 scopes and 40 encrypted columns holds up to 8,000 cache entries; the same host with a row id in the context holds one per row.

The vault cannot enforce this - it cannot tell a column name from a row id - so it is a documented rule, and the size cap above is the only mechanical backstop it has.

Records: ADR-0004 decisions 1, 2, 7 and 9, with decision 4's refusal of a caller-supplied scope pair.