Skip to content

refactor(stack-encrypt,eql-bindings)!: remove the plan chain, the builder and the old traits - #1666

Draft
coderdan wants to merge 4 commits into
feat/stack-encrypt-json-targets-owned-traitsfrom
refactor/stack-encrypt-remove-chain-and-old-traits
Draft

coderdan wants to merge 4 commits into
feat/stack-encrypt-json-targets-owned-traitsfrom
refactor/stack-encrypt-remove-chain-and-old-traits

Conversation

@coderdan

@coderdan coderdan commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Stack Encrypt (packages/stack-encrypt) is the Rust engine that every CipherStash language SDK runs on. It had two ways to encrypt a record and two ways to query one, so a developer could not tell which to use. This pull request removes the old way.

What stays is the owned API: EncryptTarget and DecryptSource with their derives, encrypt_into and decrypt_from, field markers such as EncryptedUser::EMAIL.eq(..), and dynamic::Planned for a declaration that is data. The stored bytes do not change.

It is stacked on #1664. It closes #1661 and #1662, which depend on each other, so they are one change. The second commit addresses the automated review posted below.

Changes

Removed from stack-encrypt and stack-encrypt-derive (about 6,900 lines of source)

  • The traits EncryptFrom and DecryptInto, the derives of the same names, and the calls encrypt_as and decrypt_as.
  • The plan builder and the chain: plan/chain.rs, plan/build.rs, plan/value.rs and plan/field_ref.rs. That is Plan::context(..).fields()..build(), pick, cipher.encrypt(&v)..using(&plan), cipher.query(op, v).on(&plan), cipher.open(record), plan::all, and every chain state.
  • target::Layout, tuples of targets, target::JoinContext and op::DefaultIndex. Only the builder and the chain used them.
  • The plan_build fuzz target, with its task, corpus and workflow entries. It fuzzed the builder.

Changed

  • #[derive(EncryptTarget)] and #[derive(DecryptSource)] no longer also emit the old traits.
  • DecryptField, which lets a record be a field of another record, stays. It now goes through DecryptSource.
  • The JSON targets open only to JsonPlaintext, which is wiped when it is dropped. They no longer open to a serde_json::Value.
  • eql-bindings: the EQL v4 types implement the owned traits only. JsonTree keeps encryption(), index() and specs() as its own methods.
  • The Go guest needed two comment fixes and no code change.

Added, so that the owned derives accept what the old derives accepted

  • A plaintext = T record can have a struct = .. record as a field.
  • A record with context_type = NonEmpty<T> can have a ciphertext or a term as a field.
  • A set of terms that names one index twice, or two indexes that answer one operator, is refused before any key is requested (target::check_indexes). The builder was the only thing that refused it.

Tests (about 27,000 lines touched)

  • Every test moved to the owned API, to field markers, to the combinators in stack_encrypt::target, or to a data plan.
  • tests/plan.rs is deleted. tests/plan_grammar.rs now covers the same context boundaries through the data plan, and keeps its name because the conformance script runs it. tests/combinators.rs is new and holds what survived of both.
  • 78 compile-fail cases remain of 88. Each ported case was checked to fail for its stated reason.
  • No fixture changed.

Docs

  • CHANGELOG entries with an upgrade table, a changeset for @cipherstash/eql, the crate and module docs, the derive's attribute reference, the conformance contracts, and the API plan's tracking lines.
  • The unreleased entries of both CHANGELOGs and six pending @cipherstash/eql changesets described the removed API as current. They now name the owned API, so the release notes do not tell a reader to call something that is gone.

Verification

Run on this branch:

  • mise x --env test -- cargo nextest run --workspace --all-features: 1970 passed, 2 skipped. This includes the frozen stored-bytes tests and the fixture tests, with no fixture changed.
  • The compile-fail suite (--test ui): 89 cases pass. No snapshot contains a $RUST/ snippet.
  • cargo test -p stack-encrypt --no-default-features: 894 passed. Rustdoc is clean with and without default features.
  • mise run test:doc: 112 passed. mise run doc: clean.
  • cargo clippy --workspace --all-features --all-targets -- -D warnings and cargo fmt --all --check: clean.
  • The CRAP gate (cargo crap, threshold 30): 1,591 functions, none above the threshold.
  • cargo mutants --in-diff: 32 mutants in the changed lines; 9 caught, 23 did not compile, none missed. cargo-mutants does not delete statements, so it did not see that the wipe of a refused plaintext was untested. The review found that, and owned_records::a_plaintext_is_not_leaked_when_its_indexes_are_refused now fails when the wipe is removed.
  • In packages/eql, with --locked: eql-bindings 218 passed (stack-encrypt feature) and 235 (targets feature); eql-encryption-tests 166 passed, 61 ignored; eql-codegen 202 passed, so the generated files have no drift. Clippy and fmt are clean.
  • Go: the four guests rebuilt; mise run go:test passes in all 13 packages; go:lint reports 0 issues; go generate ./... changes nothing; wasm:guest:test passes (74 and 76).
  • Conformance: the shared Rust and Go runners in scripts/stack-conformance.sh pass, and mise run test:conformance:lifecycle passes. CI caught that its enrolment still named a test this PR deleted; the second commit fixes that, and a renamed test in the EQL JSON enrolment. In test:conformance:exchange the Rust and Go halves pass. Its EQL step, and test:conformance:eql, call mise inside packages/eql, whose config is not trusted in my worktree, so CI is the evidence for those two. I ran the EQL test binary that holds the renamed enrolled test directly: 12 passed.
  • The fuzz crate compiles.

Line coverage of the code that remains. I recorded coverage before and after. It is 97.34% before and 97.17% after. 75 lines that were covered are now not covered. 72 of them are in src/json/query.rs: the typed JSON query inputs (Input<Pathed<..>>::derive), which only the chain could reach. See the first review note.

Not run locally: the 52 PostgreSQL tests of the EQL test crate, which need a database with the EQL v4 bundle. They compile, and no line of SQL in them changed. The repository script tests (pnpm run test:scripts) are not run locally either; my worktree has no node_modules.

Related

Closes #1661. Closes #1662. Part of #1488. Stacked on #1664.

Review notes

Decisions I took that you may want to change:

  1. There is no typed JSON query in Rust after this. cipher.query(op::Contains, ..).on(&plan) and op::AtPath(..) were the only typed way to query a JSON document. A JSON query now goes through a data plan (dynamic::query_term, or Planned with a query plan) until stack-encrypt: element match and jsonpath match have no typed Rust API — only the binding layer, with no compile-time checks #1459 gives the document's marker its methods. This is what the API plan says. The operator types op::Contains, op::ContainedBy and op::AtPath and the JSON index's Supports impls are still there, because the data plan uses their checks, but nothing public reaches their derive any more. stack-encrypt: element match and jsonpath match have no typed Rust API — only the binding layer, with no compile-time checks #1459 should either use them or delete them. Indexes::select (with Select, At and Whole) is in the same position: the chain was its only caller in the library. I kept it, because it is a tested public accessor that picks one index out of a set, and corrected its docs.
  2. The duplicate-index refusal is at run time, not at compile time. The plan says a typed index set such as (Equality, Equality) is refused at compile time once the builder goes. I restored the builder's refusal as a run-time check. This changes one behaviour of the API that remains: Encrypted<(OreTerm<u32>, OpeTerm<u32>)> used directly as a target was accepted before and is refused now. With today's indexes a set of four or five terms can no longer be valid, so tests/index.rs now checks sets of two and three. To drop the check, remove the two calls to check_indexes. The combinator indexed(..) composed by hand does not check, and its docs now say so.
  3. PlanError keeps variants that nothing raises now (IdentityWithoutField, MixedCiphers, TargetWithVerbs, NoContext, IndexNotDeclared, IndexOptions and others). Each has an error code that the Go status table and the error-code tests list, so removing them is a separate change.
  4. Three things have no replacement: naming another index for a query (.via(index)), choosing a keyset by name on a call (.keyset("tenant"), which loaded the keyset lazily), and a batch in which an opening with no keyset reads any keyset (plan::all). Pending::zip takes the scope of the write.
  5. A field whose type is a derived plaintext = T record has no marker method. The old plan answered op::Eq for it through indexes(). The derive writes no op::Answers for a record, by design, so a hand-written impl is needed to query it.
  6. dynamic::record::encrypt_with and decrypt_with still run the lowering themselves. 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 asked for them to build a Planned. Planned calls them today, and both share dynamic::planned::compose, so nothing observable changes either way. I left it.
  7. The enrolled fixture test names still say "chain" (the_chain_and_the_lowering_are_one_engine_today and one more), and the fixture key is typed_chain. Renaming them needs a change to conformance/stack-encrypt/v1/fixture-enrollment.json and to the fixture.

Where to look first:

  • packages/stack-encrypt/src/target/operations.rs and src/target/index.rs for the removal and the new check.
  • packages/stack-encrypt-derive/src/owned_encrypt.rs and owned_decrypt.rs for what the derives emit now.
  • packages/stack-encrypt/tests/combinators.rs and tests/plan_grammar.rs, which replace tests/plan.rs.
  • packages/stack-encrypt/CHANGELOG.md for the upgrade table.
Every deleted test, with the reason and what covers it now

"None" means the feature the test covered is removed and has no replacement.

tests/plan.rs (file deleted; 16 of its 31 tests moved to tests/combinators.rs)

Test Covered now by
a_saved_plan_is_the_same_chain_and_decrypts_back combinators::a_derived_record_is_the_hand_composed_combinators_field_for_field; planned::round_trips_with_no_caller_context
a_query_against_an_undeclared_index_or_type_is_refused ui marker_operator_not_answered, marker_query_type; query_refusal_conformance::shared_query_refusal_profile; planned::is_refused_where_no_index_answers_the_operator
decrypt_returns_what_can_come_back_and_refuses_a_mismatched_row src/dynamic/record.rs opens_back_to_the_fields_that_come_back_in_plan_order, decrypt_and_check_record_refuse_it_before_any_key_is_retrieved; ui decrypt_struct_field_not_recoverable
a_value_that_does_not_match_the_plan_is_refused_without_a_key_request src/dynamic/record.rs encrypt_and_check_source_refuse_it_alike_with_no_key_request
a_refused_chain_never_loads_the_keyset_it_names None. The chain loaded a named keyset lazily.
a_passthrough_name_need_not_be_a_label_segment plan_grammar::a_pinned_identity_keys_the_field_for_the_write_the_query_and_the_read; ui derive_query_on_a_passthrough_field
every_build_error_is_its_own src/dynamic/record.rs every_plan_refusal_maps_to_its_field_and_reason and four more; combinators::a_target_that_names_an_index_twice_is_refused_before_any_key_request
match_options_must_agree_for_a_query_to_be_declared None (.via).
all_refuses_chains_from_two_ciphers None. Pending::zip has the opposite rule: target::pendings_from_two_ciphers_over_the_same_keyset_merge.
all_lets_an_unnamed_opening_read_any_keyset None for the batch. The parts: src/target/pending.rs an_unscoped_pending_merged_with_a_scoped_one_takes_the_scope; keysets::a_mixed_keyset_column_opens_through_the_client_in_one_call_per_keyset
keyset_selects_the_minting_keyset_and_scopes_an_opening combinators::every_operation_honours_the_keyset_it_runs_through
a_plan_is_data_its_fields_say_what_they_declare plan_grammar::a_plan_says_where_its_context_comes_from
a_chain_shows_no_value markers prints_its_label_and_not_the_value; planned prints_neither_the_value_nor_the_plan
a_keyset_choice_names_what_it_holds None (KeysetChoice).
a_borrowed_string_names_a_context_and_a_keyset plan_grammar::a_context_is_a_label_or_text_that_parses_as_one

tests/plan_grammar.rs (36 tests before, 16 now; 8 moved to tests/combinators.rs)

Test Covered now by
both_starts_build_the_plan_the_context_start_builds None (the builder's two starts).
a_context_refused_at_the_call_never_loads_the_keyset_it_names The refusals stay in plan_grammar. None for the lazy load.
an_empty_batch_description_fails_on_the_context_a_chain_refuses None (chain states).
a_typed_field_answers_the_queries_its_target_declares_and_no_other combinators::a_marker_query_derives_under_the_label_the_write_used; ui marker_operator_not_answered
a_typed_field_of_terms_alone_does_not_come_back combinators::a_field_of_terms_alone_matches_its_query_and_mints_no_data_key
a_field_is_a_target_or_data_verbs_never_both src/dynamic/record.rs the_target_and_output_forms_are_exclusive
a_one_value_typed_plan_answers_its_targets_queries_and_no_other combinators::a_plaintext_record_is_the_combinators_bytes
a_one_value_plan_quotes_no_call_context_in_its_refusals None (ValuePlan).
a_one_value_plan_names_the_value_in_its_errors_never_its_context combinators::a_target_that_names_an_index_twice_is_refused_before_any_key_request
a_one_value_plan_builds_over_a_target_of_any_context None (ValuePlan).
a_vec_written_through_a_one_value_plan_opens_through_it_in_one_request combinators::a_collection_runs_in_one_request
a_picker_plan_needs_no_fields_impl_and_is_the_by_name_plans_bytes None (pick).
a_plan_naming_any_field_by_name_checks_the_value_and_one_of_pickers_does_not None (pick).
a_pinned_identity_keys_a_call_context_plan_for_query_and_open plan_grammar::a_pinned_identity_keys_the_field_for_the_write_the_query_and_the_read
a_tuple_is_decryptable_when_one_element_is None (tuples of targets).
a_terms_only_tuple_yields_to_the_ciphertext_beside_it combinators::a_record_opens_through_its_ciphertext_wherever_it_sits

tests/op.rs (33 before, 26 now)

Test Covered now by
an_operator_the_field_has_no_index_for_is_refused_when_awaited Now a compile error: ui marker_operator_not_answered. Data plan: planned is_refused_where_no_index_answers_the_operator
a_one_value_plan_answers_from_its_indexes_by_type markers answers_each_operator_through_the_index_that_answers_it
a_query_chain_debugs_without_its_value markers prints_its_label_and_not_the_value
an_undeclared_index_is_refused_before_the_query_is_prepared None (.via).
a_query_names_its_context_before_or_after_the_index None (chain grammar).
a_refused_operator_query_loads_no_keyset ui marker_operator_not_answered. The lazy load is gone.
a_field_declares_one_index_per_operator derive_plan::two_outputs_that_answer_one_operator_are_refused_before_any_request; src/dynamic/record.rs two_indexes_for_one_operator_are_refused

tests/json_index.rs (50 before, 46 now) and tests/json_owned.rs (13 before, 12 now)

Test Covered now by
json_owned the_owned_api_and_the_structural_api_open_each_others_documents None (one API now). The owned half: it_seals_from_a_json_plaintext_and_opens_to_one
given_a_plan::refuses_a_query_under_other_options None (.via). The side assertions moved to json_owned it_declares_the_json_index and the new given_the_json_index::names_its_options_in_its_spec
given_a_plan::opens_what_it_wrote_as_the_typed_open_does json_index seals_one_entry_per_node_and_opens_again
given_a_laid_out_plan::reports_its_layout given_the_json_index::names_its_options_in_its_spec
given_a_laid_out_plan::refuses_an_open_that_names_another_context src/dynamic/record.rs an_expected_context_on_a_plan_with_its_own_is_two_sources
given_a_laid_out_plan::answers_a_named_index_with_its_own_options None (.via).

tests/derive.rs (20 before, 17 now), tests/derive_plan.rs (20 before, 13 now), tests/contexts.rs (24 before, 23 now), tests/collections.rs (25 before, 24 now)

Test Covered now by
derive a_record_typed_field_is_the_derives_nested_struct derive::a_struct_nests_in_a_struct_as_an_ordinary_field; owned_equivalence::typed_generated_and_dynamic_declarations_are_one_engine
derive an_extension_reaches_a_record_typed_field_as_the_derives derive::a_struct_nests_in_a_struct_as_an_ordinary_field
derive a_struct_of_targets_is_the_derives_struct derive_plan::a_struct_record_writes_what_the_hand_written_combinators_write
derive_plan a_derived_record_as_a_typed_field_answers_its_queries derive::a_struct_is_one_batched_call_and_rebuilds_its_plaintext. See review note 5.
derive_plan a_context_field_plan_carries_and_checks_the_context owned_records::a_stored_context_opens_as_stored_and_checks_an_expectation
derive_plan a_context_field_plan_has_one_context_source None (the builder's rule).
derive_plan a_one_value_plan_with_its_own_context_refuses_the_callers None (ValuePlan).
derive_plan a_struct_record_plan_is_the_hand_written_chain Its assertions moved to a_struct_record_writes_what_the_hand_written_combinators_write
derive_plan every_derived_plan_builds None (Layout).
derive_plan a_context_field_plan_debugs_its_stored_context_and_target None (Plan's Debug).
derive_plan a_struct_record_and_its_plan_written_by_hand_open_each_other owned_equivalence::typed_generated_and_dynamic_declarations_are_one_engine
derive_plan a_context_field_record_and_its_plan_open_each_other derive_plan::a_context_field_record_writes_what_the_hand_written_combinators_write
contexts a_plan::built_without_a_context_shows_the_label_the_call_names None (the builder).
collections a_late_element_failure_wipes_the_recovered_prefix_on_the_structural_path_too collections::a_late_element_failure_wipes_the_plaintext_recovered_before_it

Compile-fail cases (tests/ui): 88 fail cases before, 78 now; 13 pass cases before, 11 now.

Case Covered now by
aead_context_with_term owned_aead_record_with_term (it was a duplicate)
bind_in_query marker_query_has_no_bind
join_context_is_sealed None (JoinContext).
op_json_not_answered No typed form. The data plan refuses it at run time: query_refusal_conformance
op_matches_on_integer, op_target_does_not_answer, plan_query_undeclared_index marker_operator_not_answered, derive_match_on_integer
part_on_structural_derive None. The owned derives accept the attribute.
plan_picker_wrong_type None (pick).
plan_empty_index_set indexes_empty_set
pass/plan_chain, pass/plan_grammar None (the chain).

Assertions that changed in a kept test

  • record_lowering: the typed side, opened under another tenant, now fails with Error::Kms, not Error::ContextMismatch. A combinator holds no expected context to compare. The data plan still answers ContextMismatch.
  • context_conformance::shared_context_boundaries: the typed opening leg ran 11 cases and now runs 4. The query cases moved to dynamic::query_term.
  • json_index: a between on a path with no ordered index was Error::Term(JsonPathNotOrdered). The data plan refuses it earlier, with Reason::OperatorNotAnswered.
  • json_leakage corpus: the sampled equality path $.tags[0] is now $.tags[*]. The typed operator read a position as a wildcard; the data plan refuses a position, and json_operators::malformed_inputs_are_refused_with_their_reason covers that refusal.
  • tests/index.rs: a_tuple_of_terms_lowers_to_the_tuple_of_their_indexes_in_order checks sets of two and three terms. See review note 2.
  • json_leakage and 12 tests of json_index now need the dynamic feature, because their queries go through the data plan.

The EQL test crate lost no test. Two compile_fail doctests for .via in eql-bindings are deleted.

@changeset-bot

changeset-bot Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 24def60

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages
Name Type
@cipherstash/eql Minor
stash Patch
@cipherstash/stack-prisma Patch
@cipherstash/basic-example Patch
@cipherstash/e2e Patch
@cipherstash/prisma-example Patch
@cipherstash/stack-drizzle Patch
@cipherstash/stack-supabase Patch
@cipherstash/stack Patch
@cipherstash/wizard Patch
@cipherstash/bench Patch
@cipherstash/test-kit Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai

coderabbitai Bot commented Nov 15, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Mutation testing (cargo-mutants, --in-diff, stack-auth + stack-encrypt)

caught missed unviable timeout
9 0 23 0

Every mutant in the changed lines was caught by a test.

@coderdan coderdan left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review by a Claude Opus subagent, requested by the author.

The library change is sound. I found no correctness or security defect in the code that remains: the new check_indexes refusals run before any key is requested, the owned refusal path wipes its plaintext, tests pin the contexts that the three new conversions give, and the JSON openings now wipe through JsonPlaintext on every path I read. The findings are a test gap on the new wipe branch, public API that lost its only consumer, and stale guidance (rustdoc, conformance contract, pending changesets) that still describes the removed API.

Findings:

  1. F1 minor: the wipe on the new refusal branch of Encrypted::owned_encryption has no test. packages/stack-encrypt/src/target/index.rs:724 (inline)
  2. F2 minor: op::DefaultIndex and Indexes::select / Select / At / Whole lost their only consumer, and their docs still describe one. packages/stack-encrypt/src/op/mod.rs:1221 (inline)
  3. F3 nit: indexed((Ore, Ope)) still produces the Encrypted<(OreTerm, OpeTerm)> that the target now refuses. packages/stack-encrypt/src/target/index.rs:191 (inline)
  4. F4 minor: public rustdoc and error text in the remaining source still describe "the query chain". Several files (below)
  5. F5 minor: the lifecycle conformance contract still claims coverage of the removed structural decrypt path. conformance/stack-encrypt/lifecycle-contract.md:15 (below)
  6. F6 minor: other stale guidance outside src/. Several files (below)
  7. F7 minor: six pending @cipherstash/eql changesets still tell users to use the API this PR removes, and they ship in the same release. .changeset/eql-remove-structural-traits.md:5 (inline)
  8. F8 nit: the test comment miscounts the kinds of index. packages/stack-encrypt/tests/combinators.rs:744 (inline)
  9. F9 nit: the CHANGELOG entry says "Three more records derive" and lists two. packages/stack-encrypt/CHANGELOG.md:12 (inline)

F4 (minor): public rustdoc and error text still describe "the query chain". Verified by reading each line at the head commit. The chain is gone. Typed queries now go through a field marker, and the data path goes through dynamic::query_term. But these docs still say a chain does the work, and two name its removed .extend(..). A reader of the published rustdoc for op::Supports, op::QueryToken, sem::MatchQuery or sem::RangeQuery is told about an API that does not exist.

  • packages/stack-encrypt/src/op/mod.rs:459 (Arity: "the chain derives a term per plaintext"), :512 (Input::derive: "Only a query chain calls this"), :779 (Supports::prepare: "A query chain calls this once"), :783 (check_label: "(.extend(..))"), :800 and :807 (Supports::query), :817 (QueryToken: "Proof that Supports::query is called by a query chain"), :1251 (test comment).
  • packages/stack-encrypt/src/sem/mod.rs:285, :868, :976 (MatchQuery "comes from a query chain"), :1089 (RangeQuery "comes only from a query chain"), :1124, :1146, :1251, :2271.
  • packages/stack-encrypt/src/sem/tokenize.rs:32; packages/stack-encrypt/src/dynamic/query.rs:1978; packages/stack-encrypt/src/dynamic/record.rs:2053 ("Some is refused as the chain refuses it"), :3347 (.fields() chain), :5322.
  • packages/stack-encrypt/src/plan/error.rs:150 and :153: the MixedCiphers message and help still say "chains" ("Start every chain in one batch on the same cipher."). Review note 3 keeps the variant. The note does not say that its user-facing text names the removed API.

Fix: replace "query chain" with "a field marker's query" or "the typed query", and replace .extend(..) with the marker's .scope(..). Reword the MixedCiphers message, or say in note 3 that it is left as is.

F5 (minor): the lifecycle contract claims coverage that was deleted. Verified. conformance/stack-encrypt/lifecycle-contract.md:15 (the lifecycle-partial-output-v1 row) still says "The same holds for a structural Vec<T> that decrypts through DecryptInto, and for a column field of a structural record." This PR deletes DecryptInto and the test that covered it (collections::a_late_element_failure_wipes_the_recovered_prefix_on_the_structural_path_too), and leaves this file unchanged. The contract now lists a guarantee that no test runs. Fix: delete that sentence, or restate it as the owned path that a_late_element_failure_wipes_the_plaintext_recovered_before_it covers.

F6 (minor): other stale guidance outside src/. Verified with git grep. Each of these describes the removed API as current:

  • packages/stack-encrypt/CONTEXT.md:24 ("a hand-written EncryptFrom type") and :71 (a target "through its own EncryptFrom"; "A plan field is either plain verbs ... or one target"). This is the crate's domain glossary.
  • packages/stack-encrypt/Cargo.toml:24: the comment says the derive dependency provides "#[derive(EncryptFrom)] / #[derive(DecryptInto)]".
  • packages/eql/AGENTS.md:97: "The same derives also implement the older EncryptFrom and DecryptInto."
  • packages/eql/crates/eql-codegen/src/targets.rs:17: "an arm runs <T as EncryptFrom<S>>::encryption()". The PR edits this file's next paragraph but not this line.
  • docs/target-directed-encryption.md:3 says "The snippets below are the API as it ships". They are all EncryptFrom. Add a status line saying the traits were later replaced, or mark it historical.
  • Go: languages/golang/encrypt/context_field_test.go:153 ("the typed chain and the data-plan lowering each sealed a Note"), and languages/golang/encrypt/query_refusal_conformance_test.go:124 and :128 (failure messages "the typed chain ..."). The first is tied to the fixture key that review note 7 keeps. The two failure messages are not, and can say "the typed query" now.

Fix: update each line. None of them needs a fixture change.

Checked and found clean:

  • check_indexes and both call sites in Encrypted<Terms>: the borrowed and owned forms both refuse before any key request. The owned form zeroizes the moved plaintext. The derived plaintext = T record checks in encryption(), and its default owned_encryption guards the value with Protected, so its refusal is wiped too. Tests combinators::a_target_that_names_an_index_twice_is_refused_before_any_key_request and derive_plan::two_outputs_* assert zero key requests.
  • The three new From impls in src/target/input.rs: derive::a_plaintext_record_field_may_be_a_record_with_declared_contexts pins the inner field's term under the extended context, and the round trip.
  • JSON: JsonExtracted, JsonSubtree, JsonDocument, JsonTreeDocument and JsonTreeExtracted keep their refusals before any key (selector check, stored-column check). opened_frame and decrypt_document now wipe by drop. I found no path where a serde_json::Value plaintext escapes unwiped.
  • eql-bindings open_target / decrypt_document: the expected-column check still runs before the opener is chosen.
  • Derive: the DecryptField impl now goes through DecryptSource, with a Zeroize bound. The removed bridges leave no dangling generics.
  • Spot-checked deleted-test claims: every_operation_honours_the_keyset_it_runs_through (keyset id on every leaf, and ForeignKeyset refusal), encrypt_and_check_source_refuse_it_alike_with_no_key_request, decrypt_and_check_record_refuse_it_before_any_key_is_retrieved, an_unscoped_pending_merged_with_a_scoped_one_takes_the_scope, and the derive_plan refusal tests. Each exists and asserts what the table says.
  • Upgrade table in packages/stack-encrypt/CHANGELOG.md: every replacement named exists with that spelling (encrypt_into_with_context, decrypt_from_with_context, KeysetCipher::encrypt_tree with &Label: IntoContext, dynamic::record::plan, dynamic::Planned::new, Pending::zip / Pending::all, StackCipher::keyset, the marker methods).
  • Repo rules: no new ignore / no_run doc blocks; no #NNNN in code comments, doc comments or READMEs (issue numbers appear only in CHANGELOGs, plans and the ADR); both crates have an Unreleased "Breaking" entry; no skills/*/SKILL.md mentions the removed API.
  • The plan_build fuzz target, its task, its corpus and both fuzz.yml matrix rows are gone. Nothing else references it.
  • No code still uses EncryptFrom, DecryptInto, encrypt_as, decrypt_as, Plan::, .using(, cipher.query(, cipher.open(, plan::all, Layout, JoinContext, ValuePlan or FieldsBuilder. Only the comments and docs listed above remain.
  • Not run: I did not run cargo. Every finding above comes from reading the code and from git grep.

{
if let Err(error) = check_indexes(&Terms::INDEXES.specs()) {
// The refused value is the description's to wipe.
return Encryption::from_build(Vec::new(), move |mut source: S, cipher, _| {

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

F1 (minor): this wipe has no test. The branch is new. It is the only thing that wipes an owned plaintext when the Encrypted<Terms> target is refused. combinators::a_target_that_names_an_index_twice_is_refused_before_any_key_request drives this path with a String. That test checks the error and the key-request count. It does not check that the plaintext was wiped. No test pairs DuplicateIndex or IndexOverlap with a wipe check (git grep over tests/ finds no witness or heap scan near either). So if someone deletes line 725, every test still passes, and a refused String is dropped without being wiped.

Verified: I read the code path and searched the tests. I did not run mutants.

Fix: add a test that encrypts a plaintext whose Zeroize sets a flag (a newtype over String that implements Encrypt by delegating, in the style of collections.rs's Tracked) into Encrypted<(EqualityTerm, EqualityTerm)>, and assert the flag is set. Or add the case to heap_hygiene.rs.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ebf5a61. owned_records::a_plaintext_is_not_leaked_when_its_indexes_are_refused encrypts a plaintext that records whether it was dropped with its value still in it. It covers Encrypted<(EqualityTerm, EqualityTerm)> alone and a plaintext = T record with two equality fields, and it asserts the error and that no key was requested. I removed the zeroize call to check: the test fails with "the refused target dropped the plaintext unwiped".

Comment thread packages/stack-encrypt/src/op/mod.rs Outdated
/// the field's type is not known where the query is written, so its
/// [`Answers`] impl is not consulted, and a field whose type answers
/// through another index needs `via`.
/// The index an operator is answered with where a field declares its

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

F2 (minor): DefaultIndex has no consumer now, and this doc says it has one. At the base commit, its only consumer was plan/chain.rs (impl<Op: DefaultIndex<In>, ..> Chooses<Op, In, Whole> for FieldPlan). git grep at the head commit finds no DefaultIndex bound or projection anywhere: only the trait, its impls here and in json/query.rs, and docs. The dynamic path reads dynamic::Op::answered_by and never this trait. But this line says it is "the table a plan that is data reads". dynamic/query.rs:11 says answered_by "is the table the typed path's DefaultIndex impls state". No test now holds the two tables to each other.

The same holds for Indexes::select, Select, At and Whole in target/index.rs. The chain was their only caller (chain.rs:850, self.indexes().select::<I, At>()). Only doctests and the select_duplicate_index UI case use them now. Their docs (index.rs:47-49, and the select method doc "for the query side, where a query asks one index for one term") still describe a query path that uses them.

Review note 1 lists the JSON operators' unreachable derive. It does not list these.

Verified with git grep at both commits.

Fix: remove DefaultIndex and select / Select / At / Whole, since this is already a breaking release. Or keep them, add them to note 1 and the CHANGELOG, and correct the two docs that claim a consumer.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ebf5a61. op::DefaultIndex and its impls are removed, and the CHANGELOG's removal entry lists it. The module docs of dynamic::query no longer claim answered_by mirrors it. I kept Indexes::select with Select, At and Whole: it is a tested public accessor (tests/index.rs, ui select_duplicate_index) that picks one index out of a set. Its docs no longer describe it as the query path, and review note 1 in the PR body now names it as API the library itself does not call.

/// the orderings, so a query for one would have to choose between them.
/// The dynamic path refuses the same declarations when it parses a plan.
///
/// A typed declaration calls this when it is described, so the refusal

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

F3 (nit): the bare combinator still makes what the target refuses. indexed (line 844) and indexed_beside do not call check_indexes. So keyset.run(indexed::<u32, _, Borrowed, _>((Ore, Ope)), &v, ctx) returns an Encrypted<(OreTerm<u32>, OpeTerm<u32>)>. Encrypting into that same type as a target is now refused with IndexOverlap. This paragraph says "A typed declaration calls this when it is described", and a reader can take indexed(..) to be one.

Verified by reading indexed and indexed_beside.

Fix: the simplest fix is to say here, and on indexed, that the bare combinator does not check. To refuse there too, note that indexed is generic over the source mode. In Owned mode a plain Encryption::failed drops the plaintext without wiping it, so a check in indexed would need the wiping branch you wrote at line 724 (and an S: Zeroize bound). Do not move the check into indexed_beside with Encryption::failed, because that would lose the wipe on the owned path.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ebf5a61, in the docs. check_indexes now says a target calls it and that indexed does not, and indexed says it does not check its set. I did not move the check into indexed_beside, for the reason you give: in Owned mode it would need the wiping branch and an S: Zeroize bound.

'@cipherstash/eql': minor
---

`eql-bindings`, the Rust crate released with this package: the EQL v4 types no longer implement Stack Encrypt's older traits `EncryptFrom` and `DecryptInto`. Stack Encrypt removed them, with `encrypt_as`, `decrypt_as`, the plan builder and the query chain.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

F7 (minor): six pending changesets still advertise the API this one removes, and they ship in the same release. packages/eql/packages/eql/CHANGELOG.md tops out at 3.0.6 and mentions none of them, so all of these are unreleased. They will appear in the same @cipherstash/eql CHANGELOG section as this entry:

  • .changeset/eql-v4-owned-targets.md:9-10: "The same derives still implement the older EncryptFrom and DecryptInto. So encrypt_as, plans ... work as before" and "To build a plan for a type, use Plan::value::<P>().encrypt_into::<T>()."
  • .changeset/eql-v4-bindings.md:5: "A Rust caller queries those types through Stack Encrypt's typed query chain: cipher.query(op::Eq, v).on(&plan)", and "through encrypt_as".
  • .changeset/eql-json-tree-walk-and-projection.md:15: "stack-encrypt gains target::Layout and Plan::value().encrypt_with_layout(layout)".
  • .changeset/eql-plan-field-targets.md:5, .changeset/eql-json-tree-domain.md:5, .changeset/eql-bindings-optional-storage-only.md:5: each names EncryptFrom / DecryptInto as what the types implement.

A reader of the release notes is told to use Plan::value and cipher.query in the same section that says they are gone.

Verified with git grep over .changeset/ and the EQL CHANGELOG.

Fix: since these are unreleased, edit them to name the owned API, or drop the sentences about the removed API.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ebf5a61. The six pending changesets name the owned API now: eql-v4-owned-targets, eql-v4-bindings, eql-json-tree-walk-and-projection, eql-plan-field-targets, eql-json-tree-domain and eql-bindings-optional-storage-only. The unreleased entries of eql-bindings/CHANGELOG.md had the same problem and are corrected too. Two of its sentences said OpeCllw and OreBlock256 implement an encryption trait; neither does any more, so I deleted them.

/// A target holds one term for each kind of index, so a target that names
/// an index twice is refused when it runs, before any key is requested:
/// alone, or as a field of a derived record. Five indexes over text always
/// repeat one. There are four kinds of index, so the fifth is a second

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

F8 (nit): there are five kinds of index over text, not four. OreBlock is Index<S> for every S: Orderable (index.rs:436), the same bound as Ore and Ope, and String meets it (this test uses OreTerm<String>). So (Equality, Match, Ore, Ope, OreBlock) repeats no index. It is refused for IndexOverlap, not DuplicateIndex. "Five indexes over text always repeat one" is therefore false. The same goes for FiveTerms' doc at line 730, "One term of each kind over text": it leaves out OreBlockTerm.

Verified by reading the bounds.

Fix: say "five kinds, and three of them answer the orderings, so no valid set has more than three", or simply that the set repeats the match index.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ebf5a61. The comment on FiveTerms now lists what it holds (equality, two match terms, ORE and OPE), and the test's doc says only that two match indexes under different options are the match index twice.

Comment thread packages/stack-encrypt/CHANGELOG.md Outdated

### Added

- **Three more records derive** (#1661). The owned derives did not accept

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

F9 (nit): "Three more records derive" lists two. The entry has two bullets (a struct record as a field of a plaintext record, and a ciphertext or term under context_type = NonEmpty<T>). The PR body's "Added" section has a third bullet, the duplicate-index refusal, which this CHANGELOG puts under "Breaking" instead.

Verified.

Fix: write "Two more records derive".

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in ebf5a61: "Two more records derive". The same pass corrected other unreleased entries of this CHANGELOG that gave decrypt_as or ValuePlan as the way to upgrade, described the old derives as current, or listed them as deprecated.

@coderdan

Copy link
Copy Markdown
Contributor Author

Replies to the findings in the review body. The inline findings (1, 2, 3, 7, 8 and 9) have their own replies.

Finding 4 (rustdoc and error text still describe "the query chain"): fixed in ebf5a61 and e418a3d. Every line listed now says "a field marker's query" or "a query", and the two .extend(..) mentions are gone. PlanError::MixedCiphers reads "the operations in one batch were started on different ciphers". Two more that the list did not have: the text of the dynamic refusal Reason::Refused ("the plan builder refused it" is now "the plan was refused"), and a comment in languages/golang/encrypt/query_test.go.

Finding 5 (the lifecycle contract claims coverage that was deleted): fixed in ebf5a61. The sentence about the structural Vec<T> is gone. The column-field half of it is still true through the owned derive (collections::a_late_element_failure_in_a_column_field_wipes_the_recovered_prefix), so the contract keeps that half. CI found the other end of the same problem: conformance/stack-encrypt/v1/lifecycle-v1.enrollment.json still enrolled the deleted test, which failed test:conformance:lifecycle. That entry is removed, and eql-json-v1.enrollment.json now names a test this pull request renamed. I checked every Rust test name in the three enrolment files against the tree: those two were the only ones missing.

Finding 6 (other stale guidance): fixed in ebf5a61. packages/stack-encrypt/CONTEXT.md, the comment in packages/stack-encrypt/Cargo.toml, packages/eql/AGENTS.md, the module docs of eql-codegen/src/targets.rs, and the three Go lines. docs/target-directed-encryption.md is a design record, so I left its snippets and added a "Superseded in part" line under its status that names the API that ships now.

…lder and the old traits

Stack Encrypt had two ways to encrypt a record and two ways to query
one. The owned API (EncryptTarget, DecryptSource, encrypt_into,
decrypt_from, field markers and dynamic::Planned) now does everything
the older one did, so the older one goes: the traits EncryptFrom and
DecryptInto with their derives, encrypt_as and decrypt_as, the plan
builder, the chain, Layout, tuples of targets and JoinContext.

The two removals depend on each other. The chain ran its fields
through the old traits, and the old traits were the only path left
into the builder, so neither compiles without the other going too.

To keep what the old derives accepted, the owned derives now take a
`struct` record as a field of a `plaintext` record, and a ciphertext
or a term as a field of a `context_type = NonEmpty<T>` record. The
builder was the only thing that refused a set of terms that names one
index twice, or two indexes that answer one operator. That refusal
moves to `target::check_indexes`, which runs before any key request.
As a result `Encrypted<Terms>` used directly as a target refuses such
a set now, where it accepted it before.

The JSON targets open only to JsonPlaintext. A typed JSON query has no
replacement yet: a JSON query goes through a data plan.

The stored bytes do not change, and no fixture changed.

Closes #1661
Closes #1662
Part of #1488
A review of the removal found one untested wipe, public API with no
caller left, and docs that still described the removed API. CI found
two conformance enrolments that named tests the removal had deleted or
renamed.

- `Encrypted<Terms>` wipes a plaintext whose set of indexes it refuses.
  No test checked that: deleting the wipe passed every test, and
  cargo-mutants does not delete statements. A test now fails without
  it, for the target alone and for a `plaintext = T` record.
- `op::DefaultIndex` is removed. Only the chain read it, and its docs
  claimed the data plan did.
- `indexed(..)` composed by hand does not check its set of indexes, as
  the target does. Its docs now say so.
- The lifecycle and EQL JSON enrolments named a deleted test and a
  renamed one, so `test:conformance:lifecycle` failed in CI.
- Rustdoc, an error message, the conformance contract, CONTEXT.md, the
  unreleased CHANGELOG entries and six pending changesets described the
  chain, `EncryptFrom`, `DecryptInto` or `encrypt_as` as current. They
  name the owned API now, so the release notes do not point a reader at
  something that is gone.

Part of #1661, #1662
…he chain

A plan refusal's text said "the plan builder refused it", and a Go test
comment named the typed Rust query chain. Neither exists any more.

Part of #1661, #1662
The plan's tracking lines were last checked on 8 November 2026, and a
week of merges made many of them wrong: it listed merged pull requests
as open, closed issues as open, and said that #1524 and this plan both
claim envelope version 0x02, although #1524 has since been closed.

Each work item now names the issues that track it as they stand on
15 November 2026, against next at 3605302 and the open stack #1613,
#1659, #1664 and #1666. Items that had no issue now name the issues
filed for them. Items that are finished say so and keep their decisions
on record. #1663, the removal of the context path type `Label`, is on
hold until the context naming work settles what that path is called.

Refs #1488, #1489

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant