refactor(stack-encrypt)!: remove target::legacy

docs/plans/2026-10-24-stack-encrypt-api-plan.md

@@ -293,8 +293,8 @@ let email = Identifier::for_column("members", "email")?;
 let age = Identifier::for_column("members", "age")?;
 
 // Not on `next` yet: the new traits for EQL types, and a borrowed value
-// and context. Today this needs `target::legacy::EncryptInto`, an owned
-// value, and an owned context.
+// and context. Today this needs `keyset.encrypt_as(&value, context)`
+// with an owned context.
 let by_email: TextEqQuery = "alice@example.com"
     .encrypt_into_with_context(&keyset, Scope::new(&email))
     .await?;
@@ -402,8 +402,8 @@ use stack_encrypt::json::JsonPlaintext;
 let column = Identifier::for_column("customers", "profile")?;
 
 // Not on `next` yet: the new traits for EQL types, and the public
-// `JsonPlaintext`. Today this needs `target::legacy::EncryptInto`, a
-// `serde_json::Value`, and an owned context.
+// `JsonPlaintext`. Today this needs `keyset.encrypt_as(&value, context)`,
+// a `serde_json::Value`, and an owned context.
 let profile: JsonPlaintext = json!({ "name": "Ada", "age": 35 }).into();
 let encrypted: JsonTreeDocument = profile
     .encrypt_into_with_context(&keyset, Scope::new(&column))
@@ -2008,10 +2008,13 @@ table.
   and the checks read them. The dynamic path no longer uses the plan
   builder. Those functions do not yet build a `Planned`: they run the
   lowering themselves. That inversion, the builder, the chain, the old
-  traits and `Label` are still to be removed.
+  traits and `Label` are still to be removed. The helpers in
+  `target::legacy` are removed, in the fourth pull request for #1488.
+  Their callers use `encrypt_as` and `decrypt_as` until those go too.
 - **Tracked in.** Issue #1488 is open. Its first pull request is the
   lowering. Its second replaces `CipherScope` and `dynamic::Scope` with
-  `CipherRef`. The removals follow.
+  `CipherRef`. Its third hides `ExpectedContext`. Its fourth removes
+  `target::legacy`. The other removals follow.
 - **Finished when** the old API is gone, and every consumer uses the new
   API.
 

packages/stack-encrypt/CHANGELOG.md

@@ -89,6 +89,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Breaking
 
+- **`target::legacy` is removed** (#1488). It held two traits,
+  implemented for every type, that gave the structural API a second
+  call syntax: `value.encrypt_into(&keyset)`,
+  `value.encrypt_into_with_context(&keyset, context)`,
+  `Target::encrypt_from(&value, &keyset, context)`,
+  `stored.decrypt_into(&cipher, context)`, `P::decrypt_from(stored, &cipher)`
+  and `P::decrypt_from_with_context(stored, &cipher, context)`. Their
+  names were the same as the owned traits' `EncryptInto` and
+  `DecryptFrom`, but they borrowed the plaintext.
+  - To upgrade a type that implements `EncryptTarget` or
+    `DecryptSource`, use the owned traits. They take the plaintext by
+    value.
+  - To upgrade a type that implements only `EncryptFrom` or
+    `DecryptInto`, call the cipher. The context is `T::Context`, so
+    convert it with `into()`:
+
+    | Removed call | Replacement |
+    | --- | --- |
+    | `value.encrypt_into(&keyset)` | `keyset.encrypt_as(&value, Default::default())` |
+    | `value.encrypt_into_with_context(&keyset, context)` | `keyset.encrypt_as(&value, context.into())` |
+    | `Target::encrypt_from(&value, &keyset, context)` | `keyset.encrypt_as::<_, Target>(&value, context.into())` |
+    | `stored.decrypt_into(&cipher, context)` | `cipher.decrypt_as(stored, context.into())` |
+    | `P::decrypt_from(stored, &cipher)` | `cipher.decrypt_as::<P, _>(stored, Default::default())` |
+    | `P::decrypt_from_with_context(stored, &cipher, context)` | `cipher.decrypt_as::<P, _>(stored, context.into())` |
+
+    `encrypt_as` does not name the target, so name it with a type
+    annotation on the result or with the turbofish shown.
+  - If `value` is already a reference, pass it as it is:
+    `keyset.encrypt_as(value, ..)`. The removed methods took the value
+    through method-call autoref, so a `&String` receiver encrypted a
+    `String`. `encrypt_as(&value, ..)` on a `&String` encrypts a
+    `&String` instead. Into a derived record that is a compile error.
+    Into `StackCipherText` it compiles, because that target accepts any
+    `Encrypt` source.
+
 - **`target::ExpectedContext` is no longer part of the API** (#1488). It
   is the check that a `#[stash(context_field)]` record runs on decrypt:
   the stored context must equal the one the caller expects, if the caller

packages/stack-encrypt/docs/adr/0012-owned-record-declarations.md

@@ -1,7 +1,7 @@
 ---
 status: accepted
 date: 2026-11-03
-revised: 2026-11-09
+revised: 2026-11-11
 extends: ADR-0003, ADR-0004
 ---
 
@@ -198,9 +198,11 @@ with a hand-written `EncryptTarget`, with the derive, and with a data plan.
 All three give the same descriptors and the same search term bytes, and each
 decrypts the records of the other two.
 
-The plan removes the structural traits, the `encrypt_as` and `decrypt_as`
-calls, and the helpers in `target::legacy`. They stay until plans, EQL, Go,
-and the guest have moved to the owned API.
+The plan removes the structural traits and the `encrypt_as` and
+`decrypt_as` calls. They stay until plans, EQL, Go, and the guest have moved
+to the owned API. The helpers in `target::legacy` were removed first. They
+were only a second way to call `encrypt_as` and `decrypt_as`, so their
+callers now call those methods.
 
 ### 6. The structural `Vec` decrypts through the wiping path
 

packages/stack-encrypt/examples/mixed_user.rs

@@ -19,7 +19,7 @@
 //!
 //! This is the *cipher-directed* layer — vitaminc's `Encrypt` / `Decrypt`
 //! derives, sealed through the keyset directly — one level below
-//! `#[derive(EncryptFrom)]`, which the
+//! `#[derive(EncryptTarget)]`, which the
 //! `encrypted_record` example uses. Reach for this layer when a value needs
 //! what the derive does not express: fields stored in the clear beside
 //! sealed ones, or a single ciphertext whose internal shape (this

packages/stack-encrypt/examples/search_terms.rs

@@ -1,7 +1,7 @@
 //! Searchable Encrypted Metadata, leaf by leaf.
 //!
 //! Shows each index-term primitive on its own through the target-directed
-//! `encrypt_into` API: equality terms (exact match), match terms (full-text
+//! owned `encrypt_into` API: equality terms (exact match), match terms (full-text
 //! containment), and ORE/OPE terms (range queries) — all generated locally
 //! from a deterministic per-keyset index key, then compared the way a server
 //! would compare them: without ever seeing a plaintext.
@@ -20,8 +20,8 @@
 
 use stack_encrypt::sem::{EqualityTerm, MatchTerms, OreTerm};
 
-use stack_encrypt::target::legacy::EncryptInto;
-use stack_encrypt::{nonempty, EncryptFrom, StackCipher, StackCipherText};
+use stack_encrypt::target::EncryptTarget;
+use stack_encrypt::{nonempty, EncryptInto, StackCipher, StackCipherText};
 
 #[tokio::main(flavor = "current_thread")]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
@@ -44,17 +44,17 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // field: the same
     // value indexed under another field can never produce a colliding term.
 
-    let stored: EqualityTerm = "alice@example.com"
+    let stored: EqualityTerm = String::from("alice@example.com")
         .encrypt_into_with_context(&terms, nonempty!("users").with("email"))
         .await?;
 
-    let hit: EqualityTerm = "alice@example.com"
+    let hit: EqualityTerm = String::from("alice@example.com")
         .encrypt_into_with_context(&terms, nonempty!("users").with("email"))
         .await?;
-    let miss: EqualityTerm = "bob@example.com"
+    let miss: EqualityTerm = String::from("bob@example.com")
         .encrypt_into_with_context(&terms, nonempty!("users").with("email"))
         .await?;
-    let wrong_field: EqualityTerm = "alice@example.com"
+    let wrong_field: EqualityTerm = String::from("alice@example.com")
         .encrypt_into_with_context(&terms, nonempty!("users").with("name"))
         .await?;
 
@@ -127,10 +127,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     //
     // Leaf by leaf is the query side. On the write side a field is stored
     // as *every* term it needs beside its ciphertext, in one shape: derive
-    // `EncryptFrom` for that shape and each field of it is derived from the
+    // `EncryptTarget` for that shape and each field of it is derived from the
     // one value under the one context — byte-identical to the leaves above,
     // so a probe built leaf by leaf finds what the record stored.
-    #[derive(EncryptFrom)]
+    #[derive(EncryptTarget)]
     #[stash(plaintext = String)]
     struct SearchableEmail {
         c: StackCipherText,
@@ -164,7 +164,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                 .encrypt_into_with_context(&terms, nonempty!("users").with("email"))
                 .await?
     );
-    let _ = record.c; // the ciphertext, opened with `decrypt_into` under the same context
+    let _ = record.c; // the ciphertext, opened with `decrypt_from_with_context` under the same context
 
     Ok(())
 }

packages/stack-encrypt/src/lib.rs

@@ -498,9 +498,9 @@ endpoint — are `StackKmsBuilder`'s, and the two keyset-cache knobs are
 //! DecryptInto)]`) encrypt a borrowed plaintext into a [`StackCipherText`].
 //! A `StackCipherText` is a tree of sealed leaves. The low-level entry
 //! points of the structural API are [`KeysetCipher::encrypt_tree`] and
-//! [`KeysetCipher::decrypt_tree`]. Its conversion helpers are in
-//! [`target::legacy`]. The structural API is separate from the owned scalar
-//! API.
+//! [`KeysetCipher::decrypt_tree`]. A declaration runs through
+//! [`KeysetCipher::encrypt_as`] and [`KeysetCipher::decrypt_as`]. The
+//! structural API is separate from the owned scalar API.
 //!
 //! The owned derives also implement the structural traits. So an owned
 //! record can be a field of a structural record, or a typed field of a plan.

packages/stack-encrypt/src/target/mod.rs

@@ -80,7 +80,7 @@
 //! # Structural API during migration
 //!
 //! The structural derives, plans, and dynamic targets still use the
-//! declarations below. Their borrowed convenience methods are isolated in [`legacy`].
+//! declarations below.
 //!
 //! [`EncryptFrom<S>`] describes ciphertext and/or term operations and has an
 //! associated context type. It does not receive plaintext or a cipher. The
@@ -167,9 +167,8 @@
 //! Implement `encryption`/`decryption`, returning core-owned descriptions, in place
 //! of `encrypt_from`/`decrypt_into` methods that took a cipher. The derives do this
 //! automatically. Call `keyset.encrypt_as(&value, context)` and
-//! `cipher.decrypt_as(record, context)`, or import [`legacy::EncryptInto`] and
-//! [`legacy::DecryptFrom`] while migrating these declarations. New scalar
-//! targets implement [`EncryptTarget`] and [`DecryptSource`].
+//! `cipher.decrypt_as(record, context)`. New scalar targets implement
+//! [`EncryptTarget`] and [`DecryptSource`].
 mod collections;
 mod context;
 mod conversion;
@@ -196,10 +195,15 @@ pub use context::{
     AeadContext, Bind, BindPart, CallerContext, CheckedInput, DeclaredContext, Extends, NoBind,
     NoScope, Parts, Scope, ScopePart, Scopes, StoredParts,
 };
+pub use conversion::{DecryptFrom, DecryptSource, EncryptInto, EncryptTarget};
 pub use index::{
     indexed, At, Encrypted, Equality, Index, IndexSpec, Indexes, Json, Match, Ope, Ore, OreBlock,
     Select, TermSet, Whole,
 };
+pub use input::{
+    AcceptsContext, AllowsNoContext, ContextInput, DeclaredScopes, NoCallerContext,
+    OptionalContext, RequiredContext, ScalarContext,
+};
 #[cfg(feature = "dynamic")]
 pub(crate) use operations::chosen;
 pub(crate) use operations::inspect;
@@ -212,23 +216,8 @@ pub use pending::{CipherRef, Pending, PendingFuture};
 pub use request::{Request, Responses};
 pub use source::{Borrowed, ConsumeSource, Owned, ShareSource, SourceMode};
 pub use stack_encrypt_derive::{DecryptInto, EncryptFrom};
-pub use tuples::JoinContext;
-
-// The old borrowed declarations remain for plans, derives and the dynamic
-// engine during the staged migration. New applications use the traits above.
-/// Borrowed conversion helpers for declarations not yet migrated to the owned API.
-/// Do not import these alongside the new conversion traits.
-pub mod legacy {
-    pub use super::operations::{
-        LegacyDecryptFrom as DecryptFrom, LegacyEncryptInto as EncryptInto,
-    };
-}
-pub use conversion::{DecryptFrom, DecryptSource, EncryptInto, EncryptTarget};
-pub use input::{
-    AcceptsContext, AllowsNoContext, ContextInput, DeclaredScopes, NoCallerContext,
-    OptionalContext, RequiredContext, ScalarContext,
-};
 pub use stack_encrypt_derive::{DecryptSource, EncryptTarget};
+pub use tuples::JoinContext;
 /// The cleanup trait that every owned plaintext must implement. It is
 /// re-exported here so that the derives can name it, even when the caller's
 /// crate does not depend on `zeroize`.

packages/stack-encrypt/src/target/operations.rs

@@ -1536,88 +1536,6 @@ impl<K: 'static> StackCipher<K> {
     }
 }
 
-/// Source-side call syntax for [`KeysetCipher::encrypt_as`], implemented for
-/// every type: `value.encrypt_into(&keyset)`. Targets implement
-/// [`EncryptFrom`], never these methods.
-pub trait LegacyEncryptInto: Sized {
-    /// Encrypt into `T` with its default context — `()` for a declaration
-    /// that carries its own contexts.
-    fn encrypt_into<'a, T, K: 'static>(&self, cipher: &'a KeysetCipher<'_, K>) -> Pending<'a, T, K>
-    where
-        T: EncryptFrom<Self>,
-        T::Context: Default,
-    {
-        cipher.encrypt_as(self, Default::default())
-    }
-    /// Encrypt into `T` under `context`, accepting anything that converts
-    /// into `T`'s context — a `nonempty!` literal, say.
-    fn encrypt_into_with_context<'a, T, K: 'static>(
-        &self,
-        cipher: &'a KeysetCipher<'_, K>,
-        context: impl Into<T::Context>,
-    ) -> Pending<'a, T, K>
-    where
-        T: EncryptFrom<Self>,
-    {
-        cipher.encrypt_as(self, context.into())
-    }
-    /// [`encrypt_into_with_context`](Self::encrypt_into_with_context) named
-    /// from the target's side: `Target::encrypt_from(&value, &keyset, ctx)`.
-    fn encrypt_from<'a, S, K: 'static>(
-        source: &S,
-        cipher: &'a KeysetCipher<'_, K>,
-        context: impl Into<<Self as EncryptFrom<S>>::Context>,
-    ) -> Pending<'a, Self, K>
-    where
-        Self: EncryptFrom<S>,
-    {
-        cipher.encrypt_as(source, context.into())
-    }
-}
-impl<T> LegacyEncryptInto for T {}
-/// Source-side call syntax for `decrypt_as`, implemented for every type:
-/// `stored.decrypt_into(&cipher, ctx)`. Targets implement [`DecryptInto`],
-/// never these methods.
-pub trait LegacyDecryptFrom: Sized + 'static {
-    /// Recover `P` through `cipher`, which may be a [`KeysetCipher`] (refusing
-    /// foreign leaves) or a [`StackCipher`] (opening any).
-    fn decrypt_into<'a, P: 'static, K: 'static>(
-        self,
-        cipher: impl Into<CipherRef<'a, K>>,
-        context: impl Into<<Self as DecryptInto<P>>::Context>,
-    ) -> Pending<'a, P, K>
-    where
-        Self: DecryptInto<P>,
-    {
-        self.decryption(context.into()).open_in(cipher)
-    }
-    /// Recover `Self` from `source` with its default context — the plain
-    /// "read the stored context and validate it" for a record that stores
-    /// one.
-    fn decrypt_from<'a, S, K: 'static>(
-        source: S,
-        cipher: impl Into<CipherRef<'a, K>>,
-    ) -> Pending<'a, Self, K>
-    where
-        S: DecryptInto<Self> + 'static,
-        S::Context: Default,
-    {
-        source.decrypt_into(cipher, S::Context::default())
-    }
-    /// Recover `Self` from `source` under `context`.
-    fn decrypt_from_with_context<'a, S, K: 'static>(
-        source: S,
-        cipher: impl Into<CipherRef<'a, K>>,
-        context: impl Into<S::Context>,
-    ) -> Pending<'a, Self, K>
-    where
-        S: DecryptInto<Self> + 'static,
-    {
-        source.decrypt_into(cipher, context.into())
-    }
-}
-impl<T: 'static> LegacyDecryptFrom for T {}
-
 // The leaf declarations below keep `Clone` on purpose. An `EncryptFrom`
 // declaration runs in the `Borrowed` mode (`encrypt_as` hands it `&S`), and an
 // operation that consumes a borrowed plaintext must clone it: the bound is