From 741fc3a2efeff805f3fbbc1edc5169f785cb83e0 Mon Sep 17 00:00:00 2001 From: JohnnyT Date: Wed, 30 Sep 2026 00:04:17 -0600 Subject: [PATCH] Restores the settled block's bullet indent The two record bullets in Encryptor.Vault.Encrypt's "Flagged, not settled" section lost their hanging indent when the block was rewritten to hold its line range. They are back in the file's style, two-space bullets with four-space continuation, and the block still runs from the heading at :57 to :84, the range ADR-0002 Amendment A cites. The section quotes the vault's ordering rule, but no record carried the sentence. A dated foot Note on ADR-0001 records it verbatim and cites, by anchor, where the encrypt path follows each step; the comment now points at that Note. No record line is removed and no decision changes. Comment and record only, so no changelog fragment. Refs: enc-6n8 --- docs/adr/0001-vault-layer.md | 29 +++++++++++++++++++++++++++++ lib/encryptor/vault/encrypt.ex | 28 ++++++++++++++-------------- 2 files changed, 43 insertions(+), 14 deletions(-) diff --git a/docs/adr/0001-vault-layer.md b/docs/adr/0001-vault-layer.md index 7efbeca..5ab477d 100644 --- a/docs/adr/0001-vault-layer.md +++ b/docs/adr/0001-vault-layer.md @@ -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. diff --git a/lib/encryptor/vault/encrypt.ex b/lib/encryptor/vault/encrypt.ex index a0b73e8..655c8ad 100644 --- a/lib/encryptor/vault/encrypt.ex +++ b/lib/encryptor/vault/encrypt.ex @@ -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