Skip to content

stack-encrypt: the plan chain and builder are still a second way to run a plan — remove them, and run their tests through Planned #1662

Open

Description

@coderdan

Background

Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. A plan says how each field of a record is encrypted. Stack Encrypt has two ways to write a plan and run it:

  • Planned. A value under a plan that is data: Planned::new(&plan, value). It is a target, so it runs through the same entry points as every other value: encrypt, encrypt_with_context, decrypt and decrypt_with_context. refactor(stack-encrypt): lower a data plan to the combinators in dynamic::planned #1597 added it.
  • The chain and the builder. A plan built in Rust code with Plan::context(..).fields(..), and run with a chain of calls: cipher.encrypt(..).using(&plan), with .context(..), .extend(..) and .keyset(..) steps.

The Stack Encrypt API plan keeps Planned and removes the chain and the builder. #1488 tracks that work.

Problem

The chain and the builder are still public. They are about 5,300 lines in packages/stack-encrypt/src/plan/. Three things follow.

  1. Two ways to do one job. A developer cannot tell which to use. The chain also let a context part added late replace an earlier one (stack-encrypt: a second .extend() replaces the first, so Rust builds a different context than Go and a query silently misses #1120, fixed), which made Rust build a different context from Go, so a query found nothing.
  2. The dynamic entry points do not use Planned. dynamic::record::encrypt_with (src/dynamic/record.rs:1798) and decrypt_with (record.rs:2097) run the lowering themselves. Planned should be the one place a data plan is run.
  3. Tests still depend on the chain. 16 test files in packages/stack-encrypt/tests, 13 compile-fail and compile-pass cases in tests/ui, and 4 files in packages/eql/tests use the chain or the builder.

What is still there, at commit 775d37645 (the head of #1659):

  • src/plan/chain.rs (1,270 lines), with three using methods (chain.rs:349, 373, 1019).
  • src/plan/build.rs (1,840 lines), with IntoLabel (build.rs:27) and the builder's output method build() (build.rs:1118).
  • src/plan/value.rs (922 lines) and src/plan/field_ref.rs (139 lines), with pick and FieldRef.
  • #[derive(EncryptFrom)] emits the builder's types (packages/stack-encrypt-derive/src/encrypt.rs:88 and 176).

Proposal

  1. Make dynamic::record::encrypt_with and decrypt_with build a Planned and run it. The lowering in dynamic::planned stays the only one.
  2. Move Plan::encryption into Planned, as the amended decision record ADR-0007 says.
  3. Move each test that uses the chain to Planned or to the typed API (field markers and the owned record derives). Planned must run every case the chain ran. List each test that is deleted, and the test that covers the same behaviour, in the pull request.
  4. Delete plan/chain.rs, plan/build.rs, plan/value.rs and plan/field_ref.rs, with pick, FieldRef, Runs, Opens and the using methods.
  5. The parent issue asks to rename the builder's output method from build() to target. Every build() in the crate is in the files this issue deletes, so there is nothing left to rename. Say so when this closes.
  6. Keep plan/error.rs and plan/values.rs if the dynamic path still uses them (dynamic/record.rs:163 imports plan::FieldValues). Move them out of plan/ if nothing else is left there.
  7. Add a "Breaking" entry to the CHANGELOG that says how to upgrade.

Acceptance

  • plan/chain.rs, plan/build.rs, plan/value.rs and plan/field_ref.rs are gone.
  • No public method is named using.
  • Every behaviour a chain test checked has a test that runs through Planned or the typed API.
  • The compile-fail cases in tests/ui still cover a binding in a query and a scope after a bind.
  • The stored bytes do not change. The frozen stored-bytes tests pass with no fixture change.
  • The Go module's tests and the cross-language conformance checks pass.

Relationship to other work

Activity

  1. self-assigned this
    on Nov 15, 2026
  2. added 3 commits that reference this issue on Nov 15, 2026
    5721065
    769102d
    ca46547
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

SDKrustPull requests that update Rust code

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions