Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions docs/adr/0001-vault-layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -1014,3 +1014,32 @@ Three things, all in this Note rather than in the record:
states nothing about this record's amendment status, so it is not a flip
site; it is an edit ADR-0005 owes, recorded here so it is not lost. ADR-0003
already cured its parallel reference in its own Note.

## Note (2026-09-30): where the vault's ordering rule is written down

`Encryptor.Vault.Encrypt`'s comment section "Flagged, not settled: the
provider is consulted on every call (settled 2026-09-13)" quotes the vault's
ordering rule to explain why the provider is resolved before the materials
cache is consulted. That sentence came from the encrypt path's implementation
bead, `enc-50m`, and no record carried it, so this Note records it. It changes
no decision and carries no status of its own.

The rule, verbatim: per call the vault "resolves the selector through the
provider, validates and maps the descriptor to a keyring, composes the
context, derives the partition id, builds the CMM stack and the client".

The encrypt path follows it at `827c6d3`:

- The provider answers first, inside the provider span:
`Resolve.encryption_key/3` at `lib/encryptor/vault/encrypt.ex:141`.
- The descriptor is validated and mapped to a keyring by `Keyring.build/3`
(`encrypt.ex:143`); a descriptor it does not know is refused at
`lib/encryptor/vault/keyring.ex:120`.
- The context is composed by `Resolve.context/5` (`encrypt.ex:144`).
- The partition id is derived as the caching CMM is built, in
`maybe_caching/3` (`encrypt.ex:192`), so only when the vault has a cache.
- The CMM stack and the client are built by `client/3` (`encrypt.ex:173`),
through `stack/3` (`encrypt.ex:160`).

The keyring therefore exists before any caching CMM does, which is the reading
ADR-0002 Amendment A's A1 settled.
28 changes: 14 additions & 14 deletions lib/encryptor/vault/encrypt.ex
Original file line number Diff line number Diff line change
Expand Up @@ -59,21 +59,21 @@ defmodule Encryptor.Vault.Encrypt do
# Two accepted records once described provider resolution differently, and
# this module was the first code that had to take a position.
#
# * ADR-0001 decision 2: encrypt and decrypt "build the engine's keyring,
# CMM, and `Client` structs per call". A keyring needs a descriptor, and
# a descriptor comes from the provider, so read literally the provider
# answers once per call.
# * ADR-0002 decision 2 said the materials cache "collapses provider round
# trips to one per partition per `max_age`". Read literally, a warm
# partition did not reach the provider at all.
# * ADR-0001 decision 2: encrypt and decrypt "build the engine's keyring,
# CMM, and `Client` structs per call". A keyring needs a descriptor, and
# a descriptor comes from the provider, so read literally the provider
# answers once per call.
# * ADR-0002 decision 2 said the materials cache "collapses provider round
# trips to one per partition per `max_age`". Read literally, a warm
# partition did not reach the provider at all.
#
# The implementation followed the first, because the vault's own ordering
# rule fixes the order in its own words - the vault "resolves the selector
# through the provider, validates and maps the descriptor to a keyring,
# composes the context, derives the partition id, builds the CMM stack and
# the client". So the keyring is built before the caching CMM is consulted,
# and what a warm cache saves is the data key generation and the EDK wrap,
# not the provider lookup.
# The implementation followed the first, because the vault's ordering rule
# (recorded in ADR-0001's Note of 2026-09-30) fixes the order: the vault
# "resolves the selector through the provider, validates and maps the
# descriptor to a keyring, composes the context, derives the partition id,
# builds the CMM stack and the client". So the keyring is built before the
# caching CMM is consulted, and what a warm cache saves is the data key
# generation and the EDK wrap, not the provider lookup.
#
# ADR-0002 Amendment A's A1 (2026-09-13) settled it on that same reading and
# withdrew decision 2's round-trip sentence: a provider is consulted on every
Expand Down
Loading