stack-encrypt: one chained plan builder as the single front door, so writes, queries and reads cannot drift #1057

Background

stack-encrypt (packages/stack-encrypt) is our Rust library for field-level encryption, with keys from ZeroKMS, our key management service. Today two separate front ends drive its engine by hand: the #[derive(EncryptFrom)] code generator, and dynamic::record (src/dynamic/record.rs), which the Go binding's WebAssembly guest runs. The design in docs/plans/2026-10-04-plan-builder.md (PR #1052, not yet merged) replaces both with one chained plan builder. A plan is the saved tail of an encrypt call with the value left out: a context, and per field its indexes. The write, the query and the read all take the same plan, so none of them can respell the context. ADR-0007 on the same PR makes the builder the only way a binding reaches the engine.

Problem

Without a builder:

• The same rules live in two places and have already drifted. The derive and dynamic::record both encode "one context per field", caller extension and batching. Nothing but tests keeps them in step, and dynamic::record's own docs record a divergence: a derive over a bare u32 seals untagged bytes while a plan seals the tagged encoding, so the same field written by each does not interchange.
• Combinators are not a usable front door. A four-field record in combinator spelling is roughly thirty lines of accepting, zip, nested-pair map and project. An Encryption is single-use and not data, so it cannot be saved in a variable or handed to Go.
• Queries can drift from writes. A query re-states the field's context by hand; if it differs, the query matches nothing, silently (the failure behind Rust TextEqQuery probes against a column written by cipherstash-client match nothing, silently #1051).

Proposal

From the plan doc's "The Rust API" and "How the builder lowers to the combinators" sections. Names are settled; exact signatures belong in the PR.

1. The chain. cipher.encrypt(&v) returns a builder holding the value and a plan under construction. .context(c) sets the context; .with(indexes) indexes a single value; .fields() switches to field by field (each top-level field sealed under <context>/<field>). Field verbs: encrypt(name) (ciphertext alone), encrypt_index(name, indexes) (ciphertext plus a non-empty index set), index(name, indexes) (indexes alone, no ciphertext; the field comes back from decrypt only if an index's output is reversible, as JSON's is), passthrough(name) (carried unsealed and unauthenticated). Then .keyset(..), .extend(parts) (the caller's parts extend every field's context, as DeclaredContext does today), and .await through IntoFuture. Before the await nothing has touched a key.
2. Saved plans. Plan::context(..) starts the same chain without a value; .build() validates the whole plan and returns an error on: a field named twice, a label that is not plain, two fields sharing one identity (the label segment a field is keyed under), passthrough on an indexed field, a value field the plan does not name (or a plan field missing from the value), or a field type that cannot be resolved. .using(&plan) runs it: cipher.encrypt(&user).using(&users_plan), and over a slice with one key request.
3. Queries. cipher.query(v).using(&field_plan) where field_plan = users_plan.field("email")?. The form is chosen by the source type; .equality() is sugar on a scalar field. A query against an index the field never declared is an error.
4. Decrypt. cipher.decrypt(row).using(&plan) returns the fields that can come back (not index-only fields with non-reversible output).
5. Batching. stack_encrypt::all((a, b)) settles several operations in one ZeroKMS request, over Pending::zip / Pending::all.
6. Lowering, not executing. Every builder call lowers to an existing combinator, per the plan doc's table: with / encrypt_index to indexed(); encrypt to ciphertext(); passthrough to passthrough(); fields() to project(select) plus .under(label) plus zip per field; using to execute-by-value; query to the selected index alone under the field's label; decrypt to open per field run by decrypt_as.
7. Native Rust keeps its two entry points. Cipher-directed encryption (the value's shape drives it, the caller supplies the context) and target-directed encryption (the output type declares what it is made from) remain the preferred entries for a Rust caller. The chain is their fluent spelling: cipher.encrypt(&v).context(c) is cipher-directed, .using(T::plan()) is target-directed through the derive. A hand-built Plan at run time is what bindings lower data into and what the derive emits.

Open question carried from the plan doc: whether a hand-built one-value plan carries its plaintext type for decrypt or the caller names it.

Relationship to other work

• Blocked by stack-encrypt: add the engine pieces the plan builder needs (passthrough, run-by-value, Index trait, per-field types) — 0.3.0 #1056 (engine additions).
• Blocks stack-encrypt-derive: #[derive(EncryptFrom)] hand-writes combinators — emit the plan builder instead #1058 (derive emits the builder), stack-encrypt: dynamic::record is a second executor that already seals differently from the derive — make it a lowering into the plan builder #1059 (dynamic::record as a lowering), Go and Rust plans cannot target EQL domains, so Go writes rows EQL cannot query — make domains plan field targets #1062 (EQL domains as field targets) and @cipherstash/stack runs a second encryption engine (protect-ffi) — new major built on stack-encrypt (umbrella) #1065 (TypeScript on stack-encrypt).
• Design: docs/plans/2026-10-04-plan-builder.md and ADR-0007 on PR docs(plans): the plan builder, one front door for stack-encrypt, the derive, the FFI and Go #1052.