docs(eql): show text encryption in Rustdoc

Make successful encryption discoverable alongside the type contracts.
Execute the displayed example in the encryption test crate so its
runtime and fake key source stay out of the bindings' default tests.
Generate plaintext/context descriptions and EQL reference links with
the Rust types so regeneration preserves them.

Refs #971

Author: coderdan

AGENTS.md

@@ -83,7 +83,7 @@ If these variables are missing, tests that require live encryption will fail or
 - `packages/utils`: Shared config (`utils/config`) and logger (`utils/logger`)
 - `packages/bench`: Performance / index-engagement benchmarks (private, not published)
 - `packages/protect-ffi`: Native FFI bindings to the CipherStash Client SDK (`@cipherstash/protect-ffi`) — the Rust core that `packages/stack` encrypts and decrypts through, absorbed from `cipherstash/protectjs-ffi`. Contains a **nested Cargo workspace** (`crates/`) and six per-platform binary packages under `platforms/*`, each published as `@cipherstash/protect-ffi-<platform>` and linked here via `workspace:*`. Also holds the repo's live FFI integration suite at `integration-tests/` — a private workspace member (`@cipherstash/ffi-integration-tests`) enrolled by its own literal entry in `pnpm-workspace.yaml`, needing Docker and credentials, and deliberately carrying **no `test` script** so `pnpm test` cannot reach it. See the "Working on protect-ffi" notes below before touching it — its default `test` and `build` are deliberately Rust-free.
-- `packages/eql`: The Encrypt Query Language subtree — the SQL bundle that stores and queries encrypted payloads — absorbed from `cipherstash/encrypt-query-language`. **The directory is the subtree root, not the package.** It was imported at a *verbatim prefix* so its repo-root-relative paths (mise tasks, `Doxyfile`, `sync-generated.mjs`) keep resolving, which puts the npm package `@cipherstash/eql` two levels down at `packages/eql/packages/eql` — the same shape as `packages/protect-ffi/platforms/*`, and enrolled the same way, by an explicit `packages/eql/packages/*` glob in `pnpm-workspace.yaml`. The subtree root deliberately carries no `package.json`. Also contains a **nested Cargo workspace** at `packages/eql/crates/` (`eql-bindings`, published in lockstep with the npm package, plus `eql-domains` / `eql-codegen` / `eql-tests-macros`, which are not), a SQLx test crate at `packages/eql/tests/sqlx`, an unpublished encryption test crate at `packages/eql/tests/encryption` (real encryption with a fake key source, plus optional PostgreSQL coverage), an ~900-line `mise.toml` task surface, its own `AGENTS.md`, and `docs/`. See the "Working on EQL" notes below before touching it.
+- `packages/eql`: The Encrypt Query Language subtree — the SQL bundle that stores and queries encrypted payloads — absorbed from `cipherstash/encrypt-query-language`. **The directory is the subtree root, not the package.** It was imported at a *verbatim prefix* so its repo-root-relative paths (mise tasks, `Doxyfile`, `sync-generated.mjs`) keep resolving, which puts the npm package `@cipherstash/eql` two levels down at `packages/eql/packages/eql` — the same shape as `packages/protect-ffi/platforms/*`, and enrolled the same way, by an explicit `packages/eql/packages/*` glob in `pnpm-workspace.yaml`. The subtree root deliberately carries no `package.json`. Also contains a **nested Cargo workspace** at `packages/eql/crates/` (`eql-bindings`, published in lockstep with the npm package, plus `eql-domains` / `eql-codegen` / `eql-tests-macros`, which are not), a SQLx test crate at `packages/eql/tests/sqlx`, an unpublished encryption test crate at `packages/eql/tests/encryption` (real encryption with a fake key source, the executable Rustdoc example at `packages/eql/crates/eql-bindings/src/encryption/example.rs`, plus optional PostgreSQL coverage), an ~900-line `mise.toml` task surface, its own `AGENTS.md`, and `docs/`. See the "Working on EQL" notes below before touching it.
   **Repository ownership:** EQL now lives in `cipherstash/stack`. File and update
   EQL issues in this repository, never in the historical
   `cipherstash/encrypt-query-language` repository. Old upstream issue and PR

SECURITY.md

@@ -28,8 +28,9 @@ same terms as the npm packages above.
 
 The `eql-encryption-tests` Rust crate (`packages/eql/tests/encryption`) is
 an unpublished test harness for these bindings. It uses real encryption with
-a fake key source and an optional disposable PostgreSQL database; it adds no
-published package or production service.
+a fake key source, executes the Rustdoc text encryption example, and provides
+optional disposable PostgreSQL coverage. It adds no published package or
+production service.
 
 > **Note on publishing.** `@cipherstash/eql` and the `eql-bindings` crate are
 > developed here but are *published* from `cipherstash/encrypt-query-language`

packages/eql/crates/eql-bindings/Cargo.toml

@@ -44,6 +44,9 @@ hex = { version = "0.4", optional = true }
 default = []
 stack-encrypt = ["dep:stack-encrypt", "dep:vitaminc-prf", "dep:base64", "dep:hex"]
 
+[package.metadata.docs.rs]
+features = ["stack-encrypt"]
+
 [dev-dependencies]
 # Parity oracle: tests/catalog_parity.rs asserts the v3 domain inventory
 # exactly covers eql_domains::CATALOG, so the types here cannot drift from

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

@@ -105,6 +105,18 @@ The optional `stack-encrypt` feature enables `EncryptFrom<String>` for `TextEq`
 and `TextEqQuery`, and `DecryptInto<String>` for `TextEq`. Other domains do not
 yet expose these conversions. The derives are emitted by `eql-codegen`.
 
+The generated API docs include a complete, executable example in the
+`eql_bindings::encryption` module, from cipher setup through decryption. Its
+[source](src/encryption/example.rs) is also run by the encryption test crate:
+
+```bash
+# From packages/eql, using the unpublished suite checkout:
+bash tasks/dev/with-stack-encrypt.sh /path/to/cipherstash-suite \
+  test -p eql-encryption-tests --test text_eq_example
+```
+
+With an initialized cipher, the essential calls are:
+
 ```rust,ignore
 use eql_bindings::{Identifier, v3::text::{TextEq, TextEqQuery}};
 

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

@@ -11,6 +11,38 @@
 //! [`TextEq`]: crate::v3::text::TextEq
 //! [`TextEqQuery`]: crate::v3::text::TextEqQuery
 //!
+//! # Example
+//!
+//! Enable the `stack-encrypt` feature on `eql-bindings`. Both targets accept
+//! a [`String`] as plaintext and a [`NonEmpty<Identifier>`] as context.
+//! [`Identifier::for_column`] validates the table and column; the returned
+//! identifier is passed directly to `encrypt_as` and stored in the output's `i`.
+//! The output type selects the encryption operations: [`TextEq`] includes
+//! ciphertext and an equality term, while [`TextEqQuery`] contains only the term.
+//!
+//! This complete example runs locally without credentials. It uses real
+//! encryption with `stack_kms::FakeDataKeySource`, whose keys exist only for
+//! this process. Add `stack-encrypt`, `stack-kms` (with `default-features = false`
+//! and `features = ["test-support"]`), and `tokio` (with `features = ["rt", "macros"]`)
+//! to your example's dependencies. Stack Encrypt is currently unpublished;
+//! use the local development helper described in the crate README.
+//!
+//! The code below is executed by `cargo test -p eql-encryption-tests --test
+//! text_eq_example`. It is excluded from this crate's doctests so its optional
+//! test key source and runtime remain in the separate encryption test crate.
+#![doc = concat!("```rust,ignore\n", include_str!("encryption/example.rs"), "\n```")]
+//!
+//! For ZeroKMS, enable Stack Encrypt's `http` feature and replace the fake-key
+//! builder with `StackCipher::new().await?`, using your configured CipherStash
+//! credentials. The encryption and decryption calls are identical.
+//!
+//! Use the same table and column identifier for writes and queries. Passing
+//! `column.into()` on decryption also checks that the stored identifier matches
+//! the expected destination before retrieving keys. `Default::default()` instead
+//! uses the stored identifier alone.
+//!
+//! # Unsupported conversions
+//!
 //! Query terms cannot recover plaintext:
 //! ```compile_fail
 //! use eql_bindings::v3::text::TextEqQuery;

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

@@ -0,0 +1,32 @@
+use eql_bindings::{
+    v3::text::{TextEq, TextEqQuery},
+    Identifier,
+};
+use stack_encrypt::StackCipher;
+use stack_kms::FakeDataKeySource;
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Local example only: these keys are held in memory, not in ZeroKMS.
+    let cipher = StackCipher::builder()
+        .kms(FakeDataKeySource::new())
+        .init()
+        .await?;
+    let keyset = cipher.default_keyset();
+    let column = Identifier::for_column("users", "email")?;
+    let email = String::from("alice@example.com");
+
+    // The output type selects ciphertext plus the equality term.
+    let stored: TextEq = keyset.encrypt_as(&email, column.clone()).await?;
+    assert_eq!(stored.i.t, "users");
+    assert_eq!(stored.i.c, "email");
+
+    // Use the same identifier to produce an equality query for this column.
+    let query: TextEqQuery = keyset.encrypt_as(&email, column.clone()).await?;
+    assert_eq!(stored.hm, query.hm);
+
+    // Decrypt to String, also checking the expected table and column.
+    let opened: String = cipher.decrypt_as(stored, column.into()).await?;
+    assert_eq!(opened, email);
+    Ok(())
+}

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

@@ -25,6 +25,13 @@
 //!
 //! Wire rule: **field names ARE wire names** — no `#[serde(rename)]`
 //! anywhere. The struct definition reads exactly like the JSON payload.
+//!
+//! Enable the `stack-encrypt` feature to encrypt Rust strings into `TextEq`
+//! storage values and `TextEqQuery` search values.
+#![cfg_attr(
+    feature = "stack-encrypt",
+    doc = "See the [complete encryption example](encryption#example), including cipher setup, table/column identifiers, and decryption."
+)]
 
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};

packages/eql/crates/eql-bindings/src/v3/bigint.rs

@@ -9,6 +9,11 @@ use ts_rs::TS;
 /// `public.eql_v3_bigint` — storage-only domain.
 ///
 /// Operators: none. Required keys: `v` `i` `c`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -40,6 +45,11 @@ impl DomainType for Bigint {
 /// `public.eql_v3_bigint_eq` — equality domain.
 ///
 /// Operators: `=` `<>`. Required keys: `v` `i` `c` `hm`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -72,6 +82,11 @@ impl DomainType for BigintEq {
 /// `public.eql_v3_bigint_ord_ore` — ordering domain.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `c` `ob`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -104,6 +119,11 @@ impl DomainType for BigintOrdOre {
 /// `public.eql_v3_bigint_ord` — ordering domain.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `c` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -136,6 +156,11 @@ impl DomainType for BigintOrd {
 /// `public.eql_v3_bigint_ord_ope` — ordering domain.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `c` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -168,6 +193,11 @@ impl DomainType for BigintOrdOpe {
 /// `eql_v3.query_bigint_eq` — equality domain query operand.
 ///
 /// Operators: `=` `<>`. Required keys: `v` `i` `hm`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -199,6 +229,11 @@ impl DomainType for BigintEqQuery {
 /// `eql_v3.query_bigint_ord_ore` — ordering domain query operand.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `ob`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -230,6 +265,11 @@ impl DomainType for BigintOrdOreQuery {
 /// `eql_v3.query_bigint_ord` — ordering domain query operand.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -261,6 +301,11 @@ impl DomainType for BigintOrdQuery {
 /// `eql_v3.query_bigint_ord_ope` — ordering domain query operand.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL bigint reference](https://cipherstash.com/docs/reference/eql/numbers) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]

packages/eql/crates/eql-bindings/src/v3/boolean.rs

@@ -9,6 +9,11 @@ use ts_rs::TS;
 /// `public.eql_v3_boolean` — storage-only domain.
 ///
 /// Operators: none. Required keys: `v` `i` `c`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL boolean reference](https://cipherstash.com/docs/reference/eql/booleans) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]

packages/eql/crates/eql-bindings/src/v3/date.rs

@@ -9,6 +9,11 @@ use ts_rs::TS;
 /// `public.eql_v3_date` — storage-only domain.
 ///
 /// Operators: none. Required keys: `v` `i` `c`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -40,6 +45,11 @@ impl DomainType for Date {
 /// `public.eql_v3_date_eq` — equality domain.
 ///
 /// Operators: `=` `<>`. Required keys: `v` `i` `c` `hm`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -72,6 +82,11 @@ impl DomainType for DateEq {
 /// `public.eql_v3_date_ord_ore` — ordering domain.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `c` `ob`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -104,6 +119,11 @@ impl DomainType for DateOrdOre {
 /// `public.eql_v3_date_ord` — ordering domain.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `c` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -136,6 +156,11 @@ impl DomainType for DateOrd {
 /// `public.eql_v3_date_ord_ope` — ordering domain.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `c` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -168,6 +193,11 @@ impl DomainType for DateOrdOpe {
 /// `eql_v3.query_date_eq` — equality domain query operand.
 ///
 /// Operators: `=` `<>`. Required keys: `v` `i` `hm`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -199,6 +229,11 @@ impl DomainType for DateEqQuery {
 /// `eql_v3.query_date_ord_ore` — ordering domain query operand.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `ob`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -230,6 +265,11 @@ impl DomainType for DateOrdOreQuery {
 /// `eql_v3.query_date_ord` — ordering domain query operand.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]
@@ -261,6 +301,11 @@ impl DomainType for DateOrdQuery {
 /// `eql_v3.query_date_ord_ope` — ordering domain query operand.
 ///
 /// Operators: `=` `<>` `<` `<=` `>` `>=`. Required keys: `v` `i` `op`.
+#[cfg_attr(doc, doc = "")]
+#[cfg_attr(
+    doc,
+    doc = " See the [EQL date reference](https://cipherstash.com/docs/reference/eql/dates-and-times) for SQL domain variants, operators, and query examples."
+)]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, TS, JsonSchema)]
 #[ts(export, export_to = "v3/")]
 #[serde(deny_unknown_fields)]