feat(eql-bindings): ship one TargetResolver for the EQL types

Stack Encrypt's dynamic interface runs a plan that arrives as data. A
field of that plan can name an EQL type, and a program gives the engine
the EQL types through the TargetResolver trait. Nobody shipped one, so
the Go guest and three EQL encryption tests each wrote the same
resolver over encryption::targets, and the copies had drifted: two test
copies named fewer of a JSON document's query domains than the guest.

encryption::EqlTargets is the guest's resolver, moved into eql-bindings
behind the targets feature. The row-to-descriptor and refusal
conversions are From impls beside it. The guest and the tests use it
and their copies are gone, so a change to the trait's signature is made
once.

Closes #1571

Author: coderdan

.changeset/eql-bindings-shared-resolver.md

@@ -0,0 +1,5 @@
+---
+"@cipherstash/eql": minor
+---
+
+`eql-bindings` (the Rust crate released with this package) now ships a resolver for Stack Encrypt's dynamic interface: `eql_bindings::encryption::EqlTargets`, behind the `targets` feature. The dynamic interface runs a plan that arrives as data, and a field of that plan can name an EQL type, such as `"TextEq"`. A program gives Stack Encrypt the EQL types through its `TargetResolver` trait. Until now each program wrote its own resolver over `encryption::targets`. `EqlTargets` holds every type in `targets::targets()` and runs a named type's `encrypt_with`, `decrypt` and `query`. Two conversions come with it: `From<&Target>` for Stack Encrypt's `TargetDescriptor`, and `From<targets::TargetError>` for Stack Encrypt's `TargetError`. Stored bytes and query operands do not change. The SQL bundle and the TypeScript types do not change.

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

@@ -1521,7 +1521,8 @@ Base64.
 - **Done already.** The functions it calls exist in `eql-bindings`:
   `encrypt_with`, `decrypt`, and `query` in `v4::targets` and
   `encryption::targets`.
-- **Tracked in.** No issue.
+- **Tracked in.** #1571. Done: the resolver is
+  `eql_bindings::encryption::EqlTargets`.
 - **Finished when** the tests and the Go guest use the resolver from
   `eql-bindings`, and their own copies are deleted.
 

languages/golang/encrypt/guest/src/targets.rs

@@ -4,32 +4,26 @@
 //! are code spans, not links: a doc build of either feature set resolves.
 //!
 //! Two builds of this crate, one resolver each (ADR-0007, amended
-//! 2026-10-06). With the `eql` feature, [`Resolver`] is `EqlTargets`,
-//! which installs `eql-bindings`' by-name dispatch
-//! (`eql_bindings::encryption::targets`): `se_targets` lists every EQL type
-//! the catalog has, and a plan field naming a producible one (`TextEq`) is
-//! run through that type's own `EncryptFrom` / `DecryptInto`, in the same
-//! ZeroKMS request as the rest of the record. Without it, [`Resolver`] is
-//! the engine's `NoTargets` (`stack_encrypt::dynamic::NoTargets`):
-//! `se_targets` lists nothing, and a plan that
-//! names a target is refused when it is parsed — at `se_plan_check`, before
-//! any value crosses.
+//! 2026-10-06). With the `eql` feature, [`Resolver`] is `eql-bindings`'
+//! own resolver (`eql_bindings::encryption::EqlTargets`): `se_targets`
+//! lists every EQL type the catalog has, and a plan field naming a
+//! producible one (`TextEq`) is run through that type's own plan, in the
+//! same ZeroKMS request as the rest of the record. Without it,
+//! [`Resolver`] is the engine's `NoTargets`
+//! (`stack_encrypt::dynamic::NoTargets`): `se_targets` lists nothing, and
+//! a plan that names a target is refused when it is parsed — at
+//! `se_plan_check`, before any value crosses.
 //!
 //! The Go module embeds both: `encrypt` the build without EQL types,
 //! `encrypt/eql` the build with them, registered on import, so a program
 //! that names an EQL type links the build that has it.
 
-#[cfg(not(feature = "eql"))]
-use stack_encrypt::dynamic::NoTargets;
-#[cfg(feature = "eql")]
-use stack_encrypt::dynamic::{TargetDescriptor, TargetError, TargetResolver};
-
 /// The resolver this build installs.
 #[cfg(feature = "eql")]
-pub type Resolver = EqlTargets;
+pub type Resolver = eql_bindings::encryption::EqlTargets;
 /// The resolver this build installs.
 #[cfg(not(feature = "eql"))]
-pub type Resolver = NoTargets;
+pub type Resolver = stack_encrypt::dynamic::NoTargets;
 
 /// This build's resolver, for the record operations.
 pub fn resolver() -> Resolver {
@@ -39,150 +33,11 @@ pub fn resolver() -> Resolver {
 /// Whether this build holds the EQL types.
 pub const HOLDS_EQL: bool = cfg!(feature = "eql");
 
-/// `eql-bindings`' by-name dispatch as the engine's resolver. The resolver
-/// sees a type name and a field's label; the field's name is the
-/// lowering's to add to a refusal.
-#[cfg(feature = "eql")]
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
-pub struct EqlTargets;
-
-#[cfg(feature = "eql")]
-impl TargetResolver for EqlTargets {
-    fn targets(&self) -> Vec<TargetDescriptor> {
-        eql_bindings::encryption::targets::targets()
-            .iter()
-            .map(describe)
-            .collect()
-    }
-
-    fn encrypt<'a, K: 'static>(
-        &self,
-        name: &str,
-        options: Option<&stack_encrypt::dynamic::TargetOptions>,
-        keyset: &'a stack_encrypt::KeysetCipher<'_, K>,
-        label: &stack_encrypt::Label,
-        plaintext: stack_encrypt::dynamic::ValueFrame,
-    ) -> Result<stack_encrypt::Pending<'a, Vec<u8>, K>, TargetError> {
-        eql_bindings::encryption::targets::encrypt_with(name, options, keyset, label, plaintext)
-            .map_err(convert)
-    }
-
-    fn decrypt<'a, K: 'static>(
-        &self,
-        name: &str,
-        cipher: &'a stack_encrypt::StackCipher<K>,
-        label: &stack_encrypt::Label,
-        stored: &[u8],
-    ) -> Result<stack_encrypt::Pending<'a, stack_encrypt::dynamic::ValueFrame, K>, TargetError>
-    {
-        eql_bindings::encryption::targets::decrypt(name, cipher, label, stored).map_err(convert)
-    }
-
-    fn query<'a, K: 'static>(
-        &self,
-        name: &str,
-        index: &stack_encrypt::target::IndexSpec,
-        keyset: &'a stack_encrypt::KeysetCipher<'_, K>,
-        label: &stack_encrypt::Label,
-        plaintext: stack_encrypt::dynamic::ValueFrame,
-    ) -> Result<stack_encrypt::Pending<'a, Vec<u8>, K>, TargetError> {
-        eql_bindings::encryption::targets::query(name, index, keyset, label, plaintext)
-            .map_err(convert)
-    }
-}
-
-/// An `eql-bindings` table row as the engine's descriptor. The two spell
-/// one wire format; `eql-bindings` tests its serde form against this
-/// crate's `to_value`.
-#[cfg(feature = "eql")]
-fn describe(target: &eql_bindings::encryption::targets::Target) -> TargetDescriptor {
-    let descriptor = TargetDescriptor::new(
-        target.name,
-        target.family,
-        target.suffix,
-        target.plaintext_kind(),
-        target.sql_domain,
-        target.indexes.iter().map(|key| (*key).to_owned()).collect(),
-        target.query.map(str::to_owned),
-        target.query_sql_domain.map(str::to_owned),
-        target.producible,
-        target.reason.map(str::to_owned),
-    );
-    // A type with a match index answers `matches` through its twin only
-    // when the engine knows the options its filter is built under.
-    let descriptor = match target.match_options() {
-        Some(options) => descriptor.with_match_options(options),
-        None => descriptor,
-    };
-    // A document's orderings at a path bind as its leaf operand, its
-    // element predicate (`element_match`) as its elements operand, and its
-    // compiled predicate (`match`) as its predicate operand.
-    let descriptor = match target.leaf_query_sql_domain() {
-        Some(domain) => descriptor.with_leaf_query_sql_domain(domain),
-        None => descriptor,
-    };
-    let descriptor = match target.elements_query_sql_domain() {
-        Some(domain) => descriptor.with_elements_query_sql_domain(domain),
-        None => descriptor,
-    };
-    match target.predicate_query_sql_domain() {
-        Some(domain) => descriptor.with_predicate_query_sql_domain(domain),
-        None => descriptor,
-    }
-}
-
-/// An `eql-bindings` refusal as the engine's. The field name is left empty:
-/// the lowering fills it in, since the resolver never sees it.
-#[cfg(feature = "eql")]
-fn convert(error: eql_bindings::encryption::targets::TargetError) -> TargetError {
-    use eql_bindings::encryption::targets::TargetError as Eql;
-    match error {
-        Eql::Unknown { name } => TargetError::Unknown { name },
-        Eql::Unproducible { name, reason } => TargetError::Unproducible {
-            name: name.to_owned(),
-            reason: reason.to_owned(),
-        },
-        Eql::NoQuery { name } => TargetError::NoQuery {
-            name: name.to_owned(),
-        },
-        Eql::Context { label } => TargetError::Column {
-            name: String::new(),
-            label,
-            reason: "an EQL column is a two-segment label, table and column".to_owned(),
-        },
-        Eql::Plaintext {
-            target,
-            expected,
-            found,
-        } => TargetError::Plaintext {
-            name: String::new(),
-            target: target.to_owned(),
-            expected: Some(expected),
-            found,
-        },
-        // The engine's code for what was wrong with the document, never
-        // the document.
-        Eql::Json { target, source } => TargetError::Json {
-            name: String::new(),
-            target: target.to_owned(),
-            reason: source.code(),
-        },
-        // The parser's kind and position, never its message: serde_json
-        // quotes the input it refused, and the input is stored ciphertext.
-        Eql::Stored { target, source } => TargetError::Stored {
-            name: String::new(),
-            target: target.to_owned(),
-            reason: stack_encrypt::diagnostic::describe_json_error(&source),
-        },
-        other => TargetError::Other(Box::new(other)),
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
     #[cfg(feature = "eql")]
-    use stack_encrypt::AsProtectedRef as _;
+    use stack_encrypt::dynamic::{TargetError, TargetResolver as _};
 
     #[cfg(not(feature = "eql"))]
     #[test]
@@ -279,112 +134,4 @@ mod tests {
             Err(TargetError::Unknown { .. })
         ));
     }
-
-    /// The JSON document's query domains this guest names, and so the JSON
-    /// operators the Go SDK is offered: the leaf operand, for the orderings
-    /// at a path; the element predicate, for `element_match`; and the
-    /// compiled predicate, for `match`. Every operator a field lists is one
-    /// the Go SDK's operator list (`parseOperatorName`) and stashgen read.
-    #[cfg(feature = "eql")]
-    #[test]
-    fn a_document_names_the_leaf_element_and_predicate_domains() {
-        use stack_encrypt::dynamic::{self, record, Op};
-        let targets = resolver().targets();
-        let document = targets
-            .iter()
-            .find(|t| t.name == "JsonSearch")
-            .expect("JsonSearch");
-        assert_eq!(
-            document.leaf_query_sql_domain.as_deref(),
-            Some("eql_v4.query_json_leaf")
-        );
-        assert_eq!(
-            document.elements_query_sql_domain.as_deref(),
-            Some("eql_v4.query_json_elements")
-        );
-        assert_eq!(
-            document.predicate_query_sql_domain.as_deref(),
-            Some("eql_v4.query_json_predicate")
-        );
-        assert!(
-            document.operators().contains(&Op::Match),
-            "the type lists match: {:?}",
-            document.operators()
-        );
-        // The operators a field answers: the orderings and `element_match`
-        // only where it orders a path, and `match` on every field.
-        let field_operators = |ordered: &[&str]| {
-            let wire = serde_json::json!({
-                "profile": {
-                    "context": ["users", "profile"],
-                    "type": "json",
-                    "null": "sql",
-                    "target": {"name": "JsonSearch", "options": {"ordered": ordered}}
-                }
-            });
-            let frame = dynamic::frame::serde::to_vec(&wire).expect("plan frame");
-            let plan = record::plan_with(frame.as_protected_ref(), &resolver()).expect("plan");
-            dynamic::field_operators(&plan, "profile", &resolver())
-                .expect("operators")
-                .into_iter()
-                .map(|(op, _)| op)
-                .collect::<Vec<_>>()
-        };
-        let ordered = field_operators(&["$.contacts[*].relationship"]);
-        for present in [Op::ElementMatch, Op::Match] {
-            assert!(ordered.contains(&present), "{present:?}: {ordered:?}");
-        }
-        let unordered = field_operators(&[]);
-        assert!(unordered.contains(&Op::Match), "{unordered:?}");
-        assert!(!unordered.contains(&Op::ElementMatch), "{unordered:?}");
-    }
-
-    #[cfg(feature = "eql")]
-    #[test]
-    fn eql_refusals_convert_to_the_engines_with_the_field_left_to_the_lowering() {
-        use eql_bindings::encryption::targets::TargetError as Eql;
-        assert!(matches!(
-            convert(Eql::Context {
-                label: "tenant/users/email".into()
-            }),
-            TargetError::Column { name, label, .. } if name.is_empty() && label == "tenant/users/email"
-        ));
-        assert!(matches!(
-            convert(Eql::Plaintext {
-                target: "TextEq",
-                expected: stack_encrypt::dynamic::ValueKind::String,
-                found: Some(stack_encrypt::dynamic::ValueKind::UInt64),
-            }),
-            TargetError::Plaintext { target, expected: Some(stack_encrypt::dynamic::ValueKind::String), .. } if target == "TextEq"
-        ));
-        // The engine asks a type's query only through an index the type
-        // carries, so one it does not is the engine's failure, not the
-        // caller's input.
-        assert!(matches!(
-            convert(Eql::NoIndex {
-                name: "TextEq",
-                index: "ope",
-            }),
-            TargetError::Other(_)
-        ));
-    }
-
-    /// serde_json quotes the value it refused, and a stored EQL value holds
-    /// ciphertext and index terms: only its kind and position cross.
-    #[cfg(feature = "eql")]
-    #[test]
-    fn a_stored_value_that_does_not_parse_quotes_none_of_it() {
-        use eql_bindings::encryption::targets::TargetError as Eql;
-        let source = serde_json::from_str::<u8>(r#""marker-ciphertext""#).unwrap_err();
-        let error = convert(Eql::Stored {
-            target: "TextEq",
-            source,
-        });
-        let TargetError::Stored { reason, .. } = &error else {
-            panic!("{error:?}");
-        };
-        assert_eq!(reason, "unexpected data at line 1 column 19");
-        let shown = format!("{error} {:?}", stack_encrypt::ErrorPayload::payload(&error));
-        assert!(!shown.contains("marker"), "{shown}");
-    }
 }

packages/eql/crates/eql-bindings/README.md

@@ -405,9 +405,9 @@ feature, and drift-gated by the same parity tests. The same generator writes
 the Go package `languages/golang/encrypt/eql` from the same rows
 (`eql-codegen go-eql`, also under `types:generate` / `types:check`). The
 engine's `TargetResolver` (stack-encrypt's `dynamic` module) is implemented
-over this module by the Go guest's `eql` build, not here: a resolver in this
-crate would need stack-encrypt API newer than the crates.io release the
-published crate names, and the guest already depends on both. A type is producible exactly
+over this module by `encryption::EqlTargets`. A program that runs data plans
+with EQL types passes `&EqlTargets` wherever the dynamic interface takes a
+resolver, as the Go guest's `eql` build does. A type is producible exactly
 when its generated struct carries the `stack-encrypt` derives
 (`ENCRYPTION_DOMAINS` in `eql-codegen`), because the dispatch runs the derived
 plan; `targets::targets()` lists them, each with `producible` and, when it is

packages/eql/crates/eql-bindings/src/encryption.rs

@@ -101,6 +101,12 @@ pub mod query;
 #[cfg(feature = "targets")]
 pub mod targets;
 
+// The EQL types as Stack Encrypt's resolver (`targets` feature).
+#[cfg(feature = "targets")]
+mod resolver;
+#[cfg(feature = "targets")]
+pub use resolver::EqlTargets;
+
 use base64::{engine::general_purpose::STANDARD, Engine as _};
 use stack_encrypt::sem::{
     EqualityTerm, MatchConfig, MatchOptions, MatchTerms, TermError, Tokenizer,