feat: upgrade to EQL v3 — cipherstash-client 0.42, typed jsonb domains, v3 typecheck & transform

ARCHITECTURE.md

@@ -4,7 +4,7 @@ This document describes the internal architecture of CipherStash Proxy. It's int
 
 ## Overview
 
-CipherStash Proxy sits between an application and PostgreSQL. It intercepts SQL statements over the PostgreSQL wire protocol, determines which columns are encrypted, rewrites queries to use [EQL v2](https://github.com/cipherstash/encrypt-query-language) operations, encrypts literals and parameters, forwards the transformed query to PostgreSQL, and decrypts results before returning them to the application.
+CipherStash Proxy sits between an application and PostgreSQL. It intercepts SQL statements over the PostgreSQL wire protocol, determines which columns are encrypted, rewrites queries to use [EQL v3](https://github.com/cipherstash/encrypt-query-language) operations, encrypts literals and parameters, forwards the transformed query to PostgreSQL, and decrypts results before returning them to the application.
 
 The two most interesting pieces of the system are:
 
@@ -112,14 +112,22 @@ When a SQL statement contains DDL (`CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`,
 
 After type inference determines which parts of a statement touch encrypted columns, the transformation pipeline rewrites the AST. Transformation rules are modular and composable — they implement a `TransformationRule` trait and are composed into a single rule via tuple implementation (supporting chains of 1 to 16 rules).
 
-The current rules:
+The current rules, in the order they are composed in
+`type_checked_statement.rs::make_transformer`:
 
 | Rule | What it does |
 |---|---|
-| `CastLiteralsAsEncrypted` | Replaces plaintext literals with `eql_v2.cast_as_encrypted(ciphertext)` |
-| `CastParamsAsEncrypted` | Wraps parameter placeholders (`$1`, `$2`, ...) with encrypted casts |
-| `RewriteContainmentOps` | Transforms `col @> val` to `eql_v2.jsonb_contains(col, val)` |
-| `RewriteStandardSqlFnsOnEqlTypes` | Rewrites `min()`, `max()`, `jsonb_path_query()` etc. to `eql_v2.*` equivalents |
+| `SubstituteEncryptedLiterals` | Replaces each plaintext literal with its ciphertext, before any rule wraps it |
+| `RewriteStandardSqlFnsOnEqlTypes` | Rewrites `min()`, `max()`, `jsonb_path_query()` etc. to their `eql_v3.*` counterparts (`count()` stays native) |
+| `RewriteContainmentOps` | Rewrites JSON `@>`/`<@` to `eql_v3.jsonb_contains`/`jsonb_contained_by`, and `->`/`->>` to `eql_v3."->"`/`"->>"` |
+| `RewriteJsonValueSelectorEq` | Fuses `col -> 'field' = value` into a single encrypted value-selector needle matched by containment |
+| `RewriteEqlComparisonOps` | Rewrites scalar comparisons: `col <op> x` → `eql_v3.<term>(col) <op> eql_v3.<term>(x)` (term chosen from the column's domain: `eq_term`/`ord_term`/`ord_term_ore`) |
+| `RewriteEqlMatchOps` | Rewrites `LIKE`/`ILIKE`/`@@` to `eql_v3.match_term(a) @> eql_v3.match_term(b)` |
+| `RewriteEqlOrderBy` | Rewrites `ORDER BY col` to order by the column's ordering term, `eql_v3.ord_term(col)` |
+| `RewriteEqlDistinct` | Rewrites `SELECT DISTINCT col` to deduplicate on the equality term, `SELECT DISTINCT ON (eql_v3.eq_term(col))` |
+| `RewriteEqlDistinctOrderBy` | Wraps a `DISTINCT` query ordered by an encrypted column in a subquery that projects the ordering term, so the outer query can order by it |
+| `RewriteEqlGroupBy` | Groups by the equality term, and lifts a projected grouped column through `eql_v3.grouped_value` |
+| `CastFullPayloadOperands` | Casts the operands with no rewrite of their own — `INSERT` and `UPDATE` values — to the column's v3 domain (`::public.eql_v3_*`). Query operands are cast to the query twin (`::eql_v3.query_*`) by the rewrite rule that produces them |
 | `PreserveEffectiveAliases` | Maintains column aliases through transformations |
 | `FailOnPlaceholderChange` | Postcondition check that prepared statement placeholders weren't corrupted |
 
@@ -191,7 +199,7 @@ When encrypting values for a statement, many columns may be `NULL` or non-encryp
 
 ## Schema Management
 
-The proxy discovers the database schema at startup and reloads it periodically. Schema loading queries PostgreSQL's `information_schema` to discover tables and columns, then checks `eql_v2_configuration` to determine which columns are encrypted and what index types they support.
+The proxy discovers the database schema at startup and reloads it periodically. Schema loading queries PostgreSQL's `information_schema` to discover tables and columns, including each column's domain type. EQL v3 columns are self-configuring domain types (e.g. `eql_v3_text_search`), so both the type-checker's capability view and the encrypt config are inferred from that single schema load — the column's domain name determines which columns are encrypted, their token type, and their searchable capabilities. There is no `eql_v2_configuration` table.
 
 Schema state is stored behind an `ArcSwap`, which provides lock-free reads with atomic updates. This means query processing never blocks on a schema reload — readers always get a consistent snapshot.
 

CHANGELOG.md

@@ -6,6 +6,42 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Changed
+
+- **EQL v3 (searchable encryption)**: Proxy now targets EQL v3. Encrypted columns are declared with self-configuring, typed `jsonb` domains (for example `eql_v3_text_search`, `eql_v3_integer_ord`, `eql_v3_json_search`) that encode both the scalar type and the column's searchable capabilities in the column type itself, replacing EQL v2's opaque `eql_v2_encrypted` composite type and its separate `eql_v2_configuration` table. The bundled `cipherstash-client` is upgraded to 0.42.0 and EQL to 3.0.3. Existing v2-encrypted data and schemas must be migrated to v3.
+
+### Added
+
+- **Encrypted full-text match with `@@`**: The `@@` operator is now supported on encrypted text columns whose domain carries a match (bloom-filter) term, rewritten to the EQL v3 `eql_v3.match_term` form.
+
+- **`SELECT DISTINCT` on an encrypted column now deduplicates**: `DISTINCT` used to compare whole encrypted payloads, whose ciphertext is randomised per row, so equal plaintexts never collapsed and `DISTINCT` silently returned duplicates. It is now keyed on the column's equality term — `SELECT DISTINCT ON (eql_v3.eq_term(col)) col …` — so one row is returned per distinct plaintext. Deduplication is equality, so a column whose domain carries no equality term (`eql_v3_boolean`, for instance, which is storage-only) is now rejected with a capability error rather than silently returning every row.
+
+- **`SELECT DISTINCT` ordered by an encrypted column**: `SELECT DISTINCT … ORDER BY <encrypted column>` now works. Ordering an encrypted column requires its ordering term, which PostgreSQL will not accept under `DISTINCT` unless it also appears in the select list, so the query is rewritten to project the term from a subquery and order the outer query by it. The term is never returned to the client and column names are preserved. Two shapes remain unsupported and are reported as such: `SELECT DISTINCT ON (…)` and `SELECT DISTINCT *`, both when combined with `ORDER BY` on an encrypted column — list the columns explicitly for the latter.
+
+- **Equality on encrypted JSON fields**: `WHERE col -> 'field' = 'value'` now works on encrypted JSON columns, in both the simple and extended query protocols, and in the `->>` and `jsonb_path_query_first(col, path) = value` spellings. `<>` is supported as the negation. The field and the value are combined into a single encrypted value-selector needle and matched by containment, so a query never reveals the field and value separately. Matching is exact and case-sensitive; the value must be a JSON scalar (comparing a whole object or array to a field is rejected — use containment with `@>` instead).
+
+### Fixed
+
+- **A param bound as both a stored value and a query operand**: `UPDATE t SET enc = $1 WHERE enc = $1` failed with a domain CHECK violation. The two occurrences need different payloads — the stored one carries the ciphertext, the query one only search terms — but the role was tracked per input param, so marking the param as a query operand stripped the ciphertext from the value being stored. The role is now taken from the rewritten statement, per occurrence.
+
+- **JSON selector params when the client declares its own types**: a client that sends param OIDs in Parse (pgx in `cache_describe` mode, for example) got `function eql_v3.jsonb_path_exists(eql_v3_json_search, jsonb) does not exist`. A JSON field selector is passed to the rewritten function as bare text, but was being declared as `jsonb` like every other encrypted operand. Affects `->`, `->>`, `jsonb_path_exists`, `jsonb_path_query` and `jsonb_path_query_first`.
+
+- **Binary-format text operands on encrypted JSON fields**: a TEXT/VARCHAR operand arriving in binary format was handed straight to the JSON decoder and rejected, even though the same value in text format was accepted. Textual types are now read as a string first and then given the text format's treatment, so `Alice` behaves like `"Alice"`.
+
+- **Aggregates over a grouped encrypted column**: `SELECT MIN(enc) FROM t GROUP BY enc` produced `grouped_value(eql_v3.min(enc))` — an aggregate inside an aggregate, which PostgreSQL rejects. An aggregate already returns one value per group, so it is no longer lifted; only a direct projection of the grouped column is.
+
+- **`SELECT *` with `GROUP BY` on an encrypted column** is now rejected with an explanatory error instead of PostgreSQL's "column must appear in the GROUP BY clause". A wildcard hides the projected columns, so the grouped column cannot be projected through `eql_v3.grouped_value` — list the columns explicitly. This matches the existing treatment of `SELECT DISTINCT *`.
+
+- **`SELECT DISTINCT *` skipped the encrypted-column protection**: a wildcard hides the columns `DISTINCT` deduplicates on, so neither the equality-term keying nor the capability check applied and duplicates were returned silently. The wildcard is now expanded to its columns, which are keyed like any other; a wildcard hiding a column with no equality term is rejected.
+
+- **`@@` with the encrypted column on the right**: `'pattern' @@ col` produced `match_term('pattern') @> match_term(col)` — a backwards containment, with the pattern never encrypted, that silently matched nothing. `@@` is symmetric in PostgreSQL, so both spellings now produce the same query.
+
+- **Encrypt config could pick up a same-named table from another schema**: the config is keyed on `(table, column)` while the schema query scanned every schema, so a table of the same name elsewhere — another tenant's, a staging copy — could overwrite the served one and give a column the wrong domain config or drop its encryption. The scan is now limited to the connection's search path, in precedence order.
+
+- **A prepared statement name reused for an unmapped statement**: `Parse` rebinds its name, but a statement Proxy does not map — `BEGIN`, `COMMIT`, or anything needing no type check — left the *previous* statement cached under that name. The next `Bind` for the name was then rewritten against a statement the client never parsed, failing with `Rewritten statement binds parameter 1, but only 0 were provided`. Affects any client that reuses the unnamed prepared statement across a transaction, which includes pgbench in extended mode and psycopg with `prepare=False`.
+
+- **`LIKE`/`ILIKE` capability checking**: `LIKE` and `ILIKE` on an encrypted column are now gated by the column's token-match capability. Previously these predicates bypassed capability checking and were silently accepted on columns that do not support fuzzy match; they are now rejected with a capability error.
+
 ## [2.2.4] - 2026-06-18
 
 ### Fixed

CLAUDE.md

@@ -8,7 +8,7 @@ CipherStash Proxy is a PostgreSQL proxy that provides **transparent, searchable
 
 Key capabilities:
 - Zero-change SQL queries - applications connect to Proxy instead of directly to PostgreSQL
-- EQL v2 (Encrypt Query Language) for searchable encryption using CipherStash ZeroKMS
+- EQL v3 (Encrypt Query Language) for searchable encryption using CipherStash ZeroKMS
 - Support for encrypted equality, comparison, ordering, and grouping operations
 - Written in Rust for performance with strongly-typed SQL statement mapping
 
@@ -34,14 +34,14 @@ Key capabilities:
 - Language-specific integration tests (Python, Go)
 
 **Showcase (`packages/showcase/`):**
-- Healthcare data model demonstrating EQL v2 encryption
+- Healthcare data model demonstrating EQL v3 encryption
 - Example of realistic encrypted application with foreign keys and relationships
 
 ### Request Flow
 
 1. Application connects to Proxy (port 6432) using standard PostgreSQL protocol
 2. Proxy intercepts SQL statements and uses EQL Mapper to analyze query structure
-3. For encrypted columns, Proxy transforms SQL using EQL v2 operations
+3. For encrypted columns, Proxy transforms SQL using EQL v3 operations
 4. Encrypted queries are sent to actual PostgreSQL database
 5. Results are decrypted before returning to application
 
@@ -166,12 +166,17 @@ Available targets: `DEVELOPMENT`, `AUTHENTICATION`, `CONFIG`, `CONTEXT`, `ENCODI
 
 ## EQL Integration
 
-CipherStash Proxy uses EQL v2 for searchable encryption. Key concepts:
+CipherStash Proxy uses EQL v3 for searchable encryption. Key concepts:
 
 - **Plaintext columns** - standard PostgreSQL data types
-- **Encrypted columns** - use `eql_v2_encrypted` type in schema
-- **Searchable operations** - equality, comparison, ordering work on encrypted data
-- **Index support** - ORE (Order Revealing Encryption) and Match indexes for performance
+- **Encrypted columns** - use a self-configuring EQL v3 domain type in the schema
+  (e.g. `eql_v3_text_search`, `eql_v3_integer_ord`, `eql_v3_json_search`); the
+  domain encodes the token type and searchable capabilities, so there is no
+  separate `add_search_config` call
+- **Searchable operations** - equality, comparison, ordering, text match, and JSON
+  traversal work on encrypted data, gated by the column's domain capability
+- **Index support** - functional indexes over the term-extraction functions
+  (e.g. `CREATE INDEX ON t (eql_v3.ord_term(col))`)
 
 EQL is automatically downloaded and installed during setup. Use `CS_EQL_PATH` to point to local EQL development version.
 

CONTEXT-MAP.md

@@ -10,9 +10,9 @@ resolved — a missing one is expected, not a gap to fill upfront.
 | Context | Path | Domain |
 |---|---|---|
 | Proxy | [`packages/cipherstash-proxy/`](./packages/cipherstash-proxy/CONTEXT.md) | PostgreSQL wire protocol, connection and message handling, client authentication, TLS, ZeroKMS key management, encrypt/decrypt of column values |
-| EQL Mapper | [`packages/eql-mapper/`](./packages/eql-mapper/CONTEXT.md) | SQL parsing, type inference over statements, schema analysis, transformation rules that rewrite plaintext SQL into EQL v2 operations |
+| EQL Mapper | [`packages/eql-mapper/`](./packages/eql-mapper/CONTEXT.md) | SQL parsing, type inference over statements, schema analysis, transformation rules that rewrite plaintext SQL into EQL v3 operations |
 | Integration | `packages/cipherstash-proxy-integration/` | End-to-end test harness — container fixtures, encrypted-scenario coverage across the proxy and mapper together |
-| Showcase | `packages/showcase/` | Healthcare example data model demonstrating EQL v2 encryption with realistic relationships |
+| Showcase | `packages/showcase/` | Healthcare example data model demonstrating EQL v3 encryption with realistic relationships |
 
 `packages/eql-mapper-macros/` is proc-macro support for EQL Mapper, not a context of its
 own — treat it as part of the EQL Mapper context.
@@ -26,22 +26,27 @@ own — treat it as part of the EQL Mapper context.
 - **Identity across the seam**: EQL Mapper's `TableColumn` and Proxy's `Identifier` are
   the same `table.column` pair under two names. That pair is the only key joining a typed
   AST node to its encryption config.
-- **Capability across the seam — currently broken.** Proxy marks every encrypted column
-  with *all* `EqlTrait`s (`packages/cipherstash-proxy/src/proxy/schema/manager.rs:146`)
-  because it derives them from the PostgreSQL column type alone. The column encrypt
-  config, which knows the SEM terms actually configured, is loaded by a separate manager
-  that never meets the schema loader. EQL Mapper's bound checking is therefore
-  unreachable in production: a query needing `Ord` on a column with no ordering SEM term
-  type-checks cleanly and fails later. Read `EqlTraits` on a column as *intended*
-  capability, not observed.
+- **Capability across the seam.** Under EQL v3 each encrypted column is a self-configuring
+  domain type (e.g. `eql_v3_text_search`) whose typname encodes both the token type and the
+  searchable capabilities. The schema loader resolves that domain to a `DomainIdentity` and
+  the exact `EqlTraits` it supports (`packages/cipherstash-proxy/src/proxy/schema/manager.rs`,
+  via `proxy/schema/eql_domains.rs`), so the traits handed to EQL Mapper are *observed*, not
+  a blanket grant. EQL Mapper's bound checking is therefore effective in production: a query
+  needing `Ord` on a column whose domain has no ordering capability is rejected at type-check
+  time. The encrypt config is derived from the same domain type
+  (`proxy/encrypt_config/from_domain.rs`), so schema view and encrypt config no longer
+  disagree.
 
 ## Shared vocabulary
 
 Terms defined once for the whole system live here rather than in any one context.
 
-- **EQL v2** — Encrypt Query Language; the SQL-level encoding that makes encrypted
+- **EQL v3** — Encrypt Query Language; the SQL-level encoding that makes encrypted
   values searchable.
-- **`eql_v2_encrypted`** — the PostgreSQL column type holding an encrypted value.
+- **EQL v3 domain types** — encrypted columns are self-configuring PostgreSQL DOMAINs over
+  `jsonb` (e.g. `eql_v3_text_search`, `eql_v3_int8_ord`, `eql_v3_json_search`). The domain's
+  typname encodes the token type and the searchable capabilities, replacing EQL v2's opaque
+  `eql_v2_encrypted` type plus a separate `eql_v2_configuration` table.
 - **ZeroKMS** — CipherStash's key management service, which the proxy calls to encrypt
   and decrypt.
 - **Keyset** — the ZeroKMS key collection a workspace encrypts against.