An encrypted :binary field, declared the way cloak_ecto declares one.

A host writes one module per encrypted type and names it from the schema:

defmodule Payments.Encrypted.Binary do
  use Encryptor.Ecto.Binary, vault: Payments.Vault
end

defmodule Payments.Cards.Card do
  use Ecto.Schema

  schema "cards" do
    field :merchant_id, :string
    field :pan, Payments.Encrypted.Binary
  end
end

The generated module implements Ecto.ParameterizedType, so changesets, queries and Repo calls keep their ordinary form and the encryption happens in the type rather than at the call site (ADR-0001 decision 1).

The option set is closed

An unknown option raises while the host module compiles, and there is no Application environment fallback for :vault: the vault is named at the declaration or the module does not compile (decision 3). Every option that could weaken the encryption context is one nobody gets, which is what makes the closed set worth its inconvenience.

What goes in the encryption context

"table" and "column", derived once at declaration time from the schema's source and the field's name, plus whatever :context adds (decision 4). The tenant is not a context pair: it passes to the vault as key:, and the vault derives and injects "tenant_ref" itself (acceptance amendment 1). A declared "table" or "column" wins over a :context pair of the same name - the derived values are the anti-substitution property and a static pair cannot be allowed to shadow them.

Schema prefixes are deliberately absent: a prefix is a deployment-time placement decision, and binding it would make a ciphertext un-restorable into a differently-prefixed database.

Because the values are frozen at declaration, renaming the physical table or column costs nothing: pin the old strings with :table and :column and stored rows stay readable.

schema "payment_cards" do
  field :pan, Payments.Encrypted.Binary, table: "cards", column: "pan"
end

A pin written at the field wins over one written at the use, which wins over the derivation. The field is where a pin usually belongs, because a type module is shared by every field that names it while a pin is about one column. Changing a declared value is the expensive direction - it invalidates every row in the column and is a re-encryption migration. And two fields must not share one declared pair, or each can decrypt the other's bytes; Encryptor.Ecto.Declarations.check_unique!/1 is the start-time check that says so, and where a host calls it.

nil, and empty

nil dumps and loads as nil, with no encryption: a NULL column stays NULL, because presence is already visible to anyone holding the database and encrypting it would break every is_nil query a host has. An empty binary is not nil and is encrypted - "" round-trips as "" (decision 7).

Failures raise; they never return :error

cast/2 keeps the ordinary :error arm, because a non-binary handed to this type genuinely is a validation failure, and cast/2 never encrypts. dump/3 and load/3 have no :error arm at all (decision 6). An Ecto.Type :error surfaces as a validation-shaped Ecto.ChangeError that a changeset can catch and proceed past, writing the row without the value it was supposed to protect - which is the wrong shape for an infrastructure failure and a dangerous one for an integrity event.

No exception message, and no Inspect of one, carries plaintext, ciphertext bytes or key material. That is structural rather than conventional: see Encryptor.Ecto.Error.

A missing tenant is an error, deliberately

With tenant: :scope - the default - the tenant comes from Encryptor.Ecto.Tenant, which the host sets at the edge of each unit of work. A dump with nothing in scope raises Encryptor.Ecto.MissingTenantError naming the table and the column (decision 5c). Not a default tenant, not a nil tenant, not a global key, not a log line: the failure that choice forbids is a row written under the wrong key because a background job forgot, which is durable and unrecoverable in a way an exception on the first test run is not.

Loads raise the same way (decision 5d). Loading with whatever context the row implies and letting the AAD check fail would work, but a raise with a legible message beats an authentication failure that reads like data corruption. Where a tenant is in scope but is the wrong one, the AAD check is the backstop: the read fails authentication and arrives as Encryptor.Ecto.DecryptError, which is the anti-substitution property working rather than a missing-scope error.

A global field: tenant: :none, and what it costs

tenant: :none declares a field global. It is written at the field, in the schema, where a reviewer sees it next to the column it applies to, and it asks no resolver anything: nothing is read from Encryptor.Ecto.Tenant, and a dump with no tenant in scope is the ordinary case rather than an error.

A :none field's ciphertexts are not crypto-shreddable with a tenant key. The tenant key is omitted from the vault call entirely, so those bytes belong to the vault's single key and nothing else. Destroying one tenant's key leaves every one of them readable, and removing that tenant's data from a :none column is an ordinary delete rather than a key-destruction. That is the trade the option is for - a lookup table, a pricing tier, a feature flag payload that no tenant owns - and it is stated here rather than left to the record, because the option is declared at the field and its consequence is a compliance one.

defmodule Payments.Encrypted.Global do
  use Encryptor.Ecto.Binary, vault: Payments.AppVault, tenant: :none
end

A :none field must name a :single-profile vault

A :tenant-profile vault carries the tenant reference in its required context set and refuses any operation without it, so "a tenant vault with the pair omitted" is not a configuration that exists. A host with both kinds of field runs two vaults: the per-tenant one its tenant-scoped fields point at, and a second single-key one its global fields point at.

The rule is checked on the first dump/3 or load/3 of such a field, and violating it raises Encryptor.Ecto.VaultProfileError naming the field, the vault it named, and the profile that vault resolved to. It cannot be checked while the declaration compiles: :context_profile is ordinary vault configuration and arrives through layers - application environment, start_link/1 options, init/1 - that do not exist at the compile time of the vault module, let alone of a type module downstream of it. The authoritative copy is the frozen Encryptor.Vault.Config the vault publishes when it starts, and this type reads it from there rather than keeping a second one.

Not queryable, and this package will not pretend otherwise

No equality lookup, no LIKE, no ordering, no unique index, no ON CONFLICT target (decision 10). Ciphertext is non-deterministic, so equal?/3 compares plaintext rather than stored bytes - otherwise every write would mark every encrypted field changed (decision 9).

The migration window: :legacy

legacy: names the type module the host was reading this column with before - a cloak_ecto type, a hand-rolled one - so that a column holding both formats at once is readable for as long as the migration takes (ADR-0001 acceptance amendment 4, ADR-0004 decision 4).

defmodule Payments.Encrypted.Binary do
  use Encryptor.Ecto.Binary,
    vault: Payments.Vault,
    legacy: Payments.Cloak.Encrypted.Binary
end

Order, and what triggers the fallback

The primary load is attempted first, always. The legacy load is attempted only when the vault refuses the stored bytes - the failure that would otherwise raise Encryptor.Ecto.DecryptError. It is not attempted for Encryptor.Ecto.MissingTenantError or Encryptor.Ecto.MissingContextError: those are host misconfiguration, they are loud on purpose, and a fallback that answered them with a successful legacy read would convert a configuration bug into a silent year of un-migrated rows (decision 4a).

The order is also what makes the window cheap. It costs one failed decrypt per legacy row and nothing at all per migrated row, and the population of legacy rows only shrinks.

Which error survives

If both loads fail, the exception raised is the primary Encryptor.Ecto.DecryptError. The legacy attempt's reason travels in that exception's non-contractual :engine field, redacted like everything else in it, and must never be matched for control flow (decision 4b). Raising the legacy error would report a self-expiring compatibility shim as the cause of what is usually a genuine integrity event.

Nothing writes through legacy, ever

dump/3 has no legacy arm and never will (decision 4c). A value read through the legacy path and written back is written in the new format, which is what makes ordinary application traffic migrate rows on its own during the window.

What the legacy module has to be

A module exporting load/1 and returning {:ok, value} | :error - the Ecto.Type shape, which is what every cloak_ecto type and every hand-rolled type already is. It is checked at the declaration rather than on the first legacy row, the way Encryptor.Ecto.Map checks its :json.

A legacy scheme behind something else - an Ecto.ParameterizedType, a sidecar service - is reachable by writing a one-function module around it, and that is the supported route: this type constructs no params for a foreign type and has no plan to construct them from. The migrator's from: accepts more shapes than this option does, because ADR-0002 decision 3 has it construct both sides' params itself and this type does not.

A zero-arity function returned by the legacy module is invoked once and its result is the value, because deferred decryption is a real convention among legacy types (cloak_ecto's closure: true) and a field that held the function rather than the value would be a defect. This mirrors the rule ADR-0004 decision 2 states for the migrator's Source contract.

Whatever the legacy module returns is the field's value as-is: this type does not re-check it, and for Encryptor.Ecto.Map that means the legacy module returns the map rather than bytes to deserialize.

The window is a security downgrade, and it is meant to end

While legacy: is set, a row that has not been rewritten yet is read under the legacy scheme's rules: for a cloak_ecto host, with no encryption context binding it to its row and no per-tenant key separation. No migrated row is weakened; the guarantee is per-row until the rewrite finishes (decision 5). Dropping legacy: is the last step of the runbook, not a thing to remember.

Every load that falls through to the legacy path emits

:telemetry.execute([:encryptor_ecto, :legacy_load], %{count: 1},
  %{table: "cards", column: "pan"})

and the metadata set is closed at those two keys: no value, no bytes, no reason, no tenant. Widening it is a security review rather than a feature (decision 5). The pair is table and column precisely because the window is per-field: a host with twelve encrypted columns finishes eleven and still has one legacy reader open.

The counter is a convenience, not proof. ADR-0004's Q4 names the reason and this documentation is the answer to it: a counter that has read zero for a retention period is evidence about traffic, not about rows, so a table with a cold partition nobody reads reports zero while still holding legacy bytes. Encryptor.Ecto.Migrator.verify/2 over sample: :all is the primary signal, and it is what a host drops legacy: on. Only the failed decrypt that preceded a successful legacy read is counted - a load that failed through both paths raises, which is louder than a counter and is not a legacy row in the sense the window is about.