docs: describe doubles fixtures + cross-ciphertext test (hm + ORE)

Author: tobyhede

CHANGELOG.md

@@ -33,7 +33,7 @@ Each entry that ships in a published release links to the PR that introduced it.
 - **`eql_v3.text` encrypted-domain family (`text`, `text_eq`, `text_match`, `text_ord`, `text_ord_ore`, `text_search`).** Adds equality (`=` / `<>` via HMAC), match (`@>` / `<@` via a new self-contained `eql_v3.bloom_filter` SEM index term), and ORE ordering (`<` `<=` `>` `>=`, `min` / `max`) for encrypted text, at parity with EQL v2 text — generated from the `text` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.int4` reference. `text` is the first scalar to add a new index `Term` (`Bloom`) and the first non-integer, unbounded ordered kind (lexicographic pivots, hand-written `impl ScalarType`). The combined **`text_search`** domain carries all three capabilities in one type — `=` / `<>` via HMAC, `<` `<=` `>` `>=` / `min` / `max` via ORE, and `@>` / `<@` via bloom filter. Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` / `eql_v3.match_term` extractors, not an operator class on the domain. Why: brings searchable encrypted text to the namespaced, `eql_v2`-free `eql_v3` surface. Match is exposed as bloom-filter containment on the `text_match` / `text_search` domains — deliberately *not* SQL `LIKE` (no wildcard/anchoring; probabilistic ngram containment) — and never backs equality. **Equality on the ordered text domains (`text_ord`, `text_ord_ore`) and on `text_search` always routes `=` / `<>` through `hm` (exact HMAC), never the ORE term — ORE is not exact-equality for text** (integer ordered domains keep exact ORE equality, which is lossless for them). ([#260](https://github.com/cipherstash/encrypt-query-language/pull/260))
 - **Self-contained `eql_v3` schema + standalone `release/cipherstash-encrypt-v3.sql` installer.** The `eql_v3` encrypted-domain surface no longer depends on `eql_v2` at runtime: it now owns its own copies of the searchable-encrypted-metadata (SEM) index-term types — `eql_v3.hmac_256` and `eql_v3.ore_block_256` (with its btree operator class) — so the `eql_v3.eq_term` / `eql_v3.ord_term` extractors return `eql_v3` types and no `eql_v2.<symbol>` appears anywhere in the v3 SQL. The whole v3 surface relocated under a single `src/v3/` tree (`src/v3/sem/` for the hand-written SEM types, `src/v3/scalars/` for the generated domain families). A new build variant ships the `eql_v3` schema on its own as `release/cipherstash-encrypt-v3.sql`, installable into a database with no `eql_v2` present; a CI gate greps that artifact and its dependency closure to keep it `eql_v2`-free. Why: a clean foundation for the per-scalar encrypted-domain model to stand alone, ahead of it replacing the `eql_v2_encrypted` composite column type. This is additive — a new schema and a new artifact — and leaves `eql_v2` byte-for-byte unchanged. ([#255](https://github.com/cipherstash/encrypt-query-language/pull/255))
 - **`eql_v3.text` encrypted-domain family (`text`, `text_eq`, `text_match`, `text_ord`, `text_ord_ore`).** Adds equality (`=` / `<>` via HMAC), match (`@>` / `<@` via a new self-contained `eql_v3.bloom_filter` SEM index term), and ORE ordering (`<` `<=` `>` `>=`, `min` / `max`) for encrypted text, at parity with EQL v2 text — generated from the `text` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.int4` reference. `text` is the first scalar to add a new index `Term` (`Bloom`) and the first non-integer, unbounded ordered kind (lexicographic pivots, hand-written `impl ScalarType`). Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` / `eql_v3.match_term` extractors, not an operator class on the domain. Why: brings searchable encrypted text to the namespaced, `eql_v2`-free `eql_v3` surface. Match is exposed as bloom-filter containment on the `text_match` domain — deliberately *not* SQL `LIKE` (no wildcard/anchoring; probabilistic ngram containment) — and never backs equality (which always routes through `Hm`). ([#260](https://github.com/cipherstash/encrypt-query-language/pull/260))
-- **Property-based tests for the `eql_v3` encrypted scalar domains.** A harness of three suites asserts SQL operator results agree with a plaintext oracle across a generated input space: a pure-Rust **catalog** suite (no database) over the term/scalar catalog, a **fixture** suite that runs an all-pairs oracle over the committed real-ciphertext fixtures (the curated catalog values per type), and an **e2e** suite (gated behind the `proptest-e2e` cargo feature) that batch-encrypts freshly generated plaintexts end-to-end through ZeroKMS each run. Beyond the operator oracles, the fixture suite drives **function-double** oracles — the generated `eql_v3.eq`/`neq`/`lt`/`lte`/`gt`/`gte` functions across all three overloads (domain–domain, domain–jsonb, jsonb–domain) — plus **term-extractor identity** (`eq_term`==`hm`, `ord_term`==`ob`) and an example-based bloom **match** smoke for the text `_match` domain. Covers the equality (`=`/`<>`) and ordering (`<`/`<=`/`>`/`>=`, `ord_term` sort order) operator and function oracles plus NULL/blocker/CHECK edge cases, across every fixtured scalar (`int2`/`int4`/`int8`/`date`/`timestamptz`/`numeric`/`text`). The e2e suite — which appends fresh duplicate plaintexts each run — is the one that exercises equality across two independent encryptions of one value. Why: the prior matrix exercised fixed pivots only; property tests over the whole fixture set catch operator/oracle disagreements across the value space, and the e2e suite adds defence in depth by re-encrypting every run rather than pinning a frozen ciphertext snapshot. ([#293](https://github.com/cipherstash/encrypt-query-language/pull/293))
+- **Property-based tests for the `eql_v3` encrypted scalar domains.** A harness of three suites asserts SQL operator results agree with a plaintext oracle across a generated input space: a pure-Rust **catalog** suite (no database) over the term/scalar catalog, a **fixture** suite that runs an all-pairs oracle over the committed real-ciphertext fixtures (the curated catalog values per type), and an **e2e** suite (gated behind the `proptest-e2e` cargo feature) that batch-encrypts freshly generated plaintexts end-to-end through ZeroKMS each run. Beyond the operator oracles, the fixture suite drives **function-double** oracles — the generated `eql_v3.eq`/`neq`/`lt`/`lte`/`gt`/`gte` functions across all three overloads (domain–domain, domain–jsonb, jsonb–domain) — plus **term-extractor identity** (`eq_term`==`hm`, `ord_term`==`ob`) and an example-based bloom **match** smoke for the text `_match` domain. Covers the equality (`=`/`<>`) and ordering (`<`/`<=`/`>`/`>=`, `ord_term` sort order) operator and function oracles plus NULL/blocker/CHECK edge cases, across every fixtured scalar (`int2`/`int4`/`int8`/`date`/`timestamptz`/`numeric`/`text`). Equality across two independent encryptions of one value is exercised credential-free by the fixture suite via committed per-type *doubles* fixtures (each plaintext encrypted twice — `property::cross_ciphertext`), through both the `hm` (`_eq`) and ORE (`_ord`/`_ord_ore`) equality paths, and additionally by the e2e suite via fresh duplicate plaintexts each run. Why: the prior matrix exercised fixed pivots only; property tests over the whole fixture set catch operator/oracle disagreements across the value space, and the e2e suite adds defence in depth by re-encrypting every run rather than pinning a frozen ciphertext snapshot. ([#293](https://github.com/cipherstash/encrypt-query-language/pull/293))
 - **Self-contained `eql_v3` schema + standalone `release/cipherstash-encrypt-v3.sql` installer.** The `eql_v3` encrypted-domain surface no longer depends on `eql_v2` at runtime: it now owns its own copies of the searchable-encrypted-metadata (SEM) index-term types — `eql_v3.hmac_256` and `eql_v3.ore_block_u64_8_256` (with its btree operator class) — so the `eql_v3.eq_term` / `eql_v3.ord_term` extractors return `eql_v3` types and no `eql_v2.<symbol>` appears anywhere in the v3 SQL. The whole v3 surface relocated under a single `src/v3/` tree (`src/v3/sem/` for the hand-written SEM types, `src/v3/scalars/` for the generated domain families). A new build variant ships the `eql_v3` schema on its own as `release/cipherstash-encrypt-v3.sql`, installable into a database with no `eql_v2` present; a CI gate greps that artifact and its dependency closure to keep it `eql_v2`-free. Why: a clean foundation for the per-scalar encrypted-domain model to stand alone, ahead of it replacing the `eql_v2_encrypted` composite column type. This is additive — a new schema and a new artifact — and leaves `eql_v2` byte-for-byte unchanged. ([#255](https://github.com/cipherstash/encrypt-query-language/pull/255))
 - **`eql_v3.min` / `eql_v3.max` aggregates over `eql_v3.ste_vec_entry`.** SteVec document entries extracted at a selector (`doc -> 'sel'`) can now be aggregated like ordered scalars: `eql_v3.min(doc -> 'sel')` / `eql_v3.max(...)` return the entry with the smallest / largest ordered leaf. Ordering routes through the entry's `oc` (CLLW ORE) term via `eql_v3.ore_cllw` — the same comparator the entry `<` / `<=` / `>` / `>=` operators use, not the scalar Block-ORE `ord_term`. Only `oc`-carrying entries are orderable: an entry without an `oc` term (`eql_v3.ore_cllw` returns NULL) is non-orderable and is ignored by the aggregate — the same way the `eql_v3.ore_cllw` btree NULL-filters such rows — so a mix of `oc`-carrying and `oc`-less entries yields the extremum of the orderable subset rather than a corrupted result. Declared `PARALLEL = SAFE` with a combine function (the state function itself), so partial / parallel aggregation is available on large `GROUP BY` workloads. Why: brings encrypted-JSONB entry ordering to parity with the scalar encrypted-domain families' `MIN` / `MAX`, and lets the shared scalar behaviour matrix cover entry aggregation. Additive — the document and entry comparison surface is otherwise unchanged. ([#267](https://github.com/cipherstash/encrypt-query-language/pull/267))
 - **`eql_v3.bool` encrypted-domain type family (storage-only / encryption-only).** A single jsonb-backed domain for encrypted `bool` columns — `eql_v3.bool` — generated from the `bool` row in `eql-scalars::CATALOG`. Unlike every other scalar family, `bool` is **encryption-only**: it carries no SEM index term and exposes **no** `_eq` / `_ord` domains, so the value is encrypted at rest and decrypted by the proxy but is **not searchable server-side**. This is deliberate — a two-value column has so little cardinality that any searchable index (even HMAC equality) would trivially leak the plaintext distribution. Every comparison / containment / path operator reachable through domain fallback (`=`, `<>`, `<`, `<=`, `>`, `>=`, `@>`, `<@`, `->`, `->>`, …) is blocked (raises rather than silently routing to plaintext-`jsonb` semantics); the domain `CHECK` still requires the EQL envelope (`v`, `i`), the ciphertext (`c`), and pins the payload version (`VALUE->>'v' = '2'`). The encrypted payload is `{v,i,c}` only — no `hm` / `ob` / `bf` term. Why: lets callers encrypt a low-cardinality boolean column at rest without offering a server-side search surface that would leak it; the first **storage-only** member of the generated scalar encrypted-domain family. ([#295](https://github.com/cipherstash/encrypt-query-language/pull/295))

docs/analysis/2026-06-11-v3-scalar-vs-jsonb-test-coverage.md

@@ -130,6 +130,15 @@ Source of truth: `crates/eql-scalars/src` (`CATALOG`). Adding a type is one `Sca
 
 Domain → role: empty ⇒ Storage, first term `Hm` ⇒ Eq, `Ore` ⇒ Ord, `Bloom` ⇒ Match.
 
+**Cross-ciphertext equality** ("two independent encryptions of one value compare
+equal") is now covered credential-free for every comparison scalar by the fixture
+suite, via committed per-type *doubles* tables (`fixtures.eql_v2_<T>_doubles` — each
+plaintext encrypted twice) read by `property::cross_ciphertext`. It exercises both
+equality mechanisms: the `hm` path (`_eq`) and the ORE `ob` path (`_ord` /
+`_ord_ore`, where `=` routes through `compare_ore_block_256_terms(...) = 0`). The
+matrix's curated fixtures have unique plaintexts, so the doubles tables are what
+make the equality-across-distinct-ciphertext branch fire without fresh encryption.
+
 **Generated surface per domain:** domain definition + CHECK, extractors (inlinable `LANGUAGE sql`), supported-op wrappers (inlinable), **blockers** (`LANGUAGE plpgsql`, NOT STRICT — opaque to planner so the `RAISE` always survives), 44 `CREATE OPERATOR`s, and `min`/`max` aggregates for ord-capable domains. Blocker count per domain: Storage 44, Eq 38, Ord 26, Match 38.
 
 **Behavioural blocker coverage caveat:** the scalar matrix does not execute every generated operator signature per domain. It covers the important caller-visible blocker classes: unsupported comparison/containment operators, typed-column `col op col` blockers, scalar path blockers (`->`, `->>`), and native-absent LIKE/ILIKE resolution. It does not sweep every generated JSON-style signature such as `?`, `?|`, `?&`, `@?`, `@@`, `#>`, `#>>`, `-`, `#-`, and `||` for every scalar domain.

tests/sqlx/tests/encrypted_domain/property/README.md

@@ -17,11 +17,13 @@ named for what they operate on, not by an abstract tier letter:
 | **fixture** | [`fixture_oracle.rs`](./fixture_oracle.rs) | integration | committed fixture rows (real ciphertext) | isolated per-test DB (`#[sqlx::test]`) |
 | **e2e** | [`e2e_oracle.rs`](./e2e_oracle.rs) | integration | freshly generated plaintexts, encrypted each run | shared test DB **+ ZeroKMS creds** |
 
-The `fixture` suite spans two files: [`fixture_oracle.rs`](./fixture_oracle.rs)
-(the operator **and** function-double oracles + term-extractor identity) and
-[`match_smoke.rs`](./match_smoke.rs) (example-based bloom containment for the text
-`_match` domain). Both are un-gated — they read the already-encrypted fixtures,
-no fresh ZeroKMS.
+The `fixture` suite spans several files: [`fixture_oracle.rs`](./fixture_oracle.rs)
+(the operator **and** function-double oracles + term-extractor identity),
+[`cross_ciphertext.rs`](./cross_ciphertext.rs) (proves two independent
+encryptions of one value compare equal, over the committed per-type *doubles*
+fixtures), and [`match_smoke.rs`](./match_smoke.rs) (example-based bloom
+containment for the text `_match` domain). All are un-gated — they read the
+already-encrypted fixtures, no fresh ZeroKMS.
 
 Plus [`edge_cases.rs`](./edge_cases.rs): example-based unit tests for
 NULL propagation, blockers raising on unsupported operators (including the
@@ -55,6 +57,16 @@ identity** — `eql_v3.eq_term` returns the payload's exact `hm`, `eql_v3.ord_te
 returns its exact `ob`. [`match_smoke.rs`](./match_smoke.rs) adds the
 example-based bloom containment (`@>`/`<@`) for the text `_match` domain.
 
+Cross-ciphertext equality — "two independent encryptions of one value compare
+equal" — needs equal-plaintext / distinct-ciphertext rows, which the curated
+matrix fixture (unique plaintexts) has no room for. So each comparison type
+carries a tiny sibling table, `fixtures.eql_v2_<T>_doubles` (generated by
+[`fixtures::eql_doubles`](../../../src/fixtures/eql_doubles.rs)): the first three
+catalog values, each encrypted twice. [`cross_ciphertext.rs`](./cross_ciphertext.rs)
+reads ONLY those tables and proves the equality holds through both the `hm`
+(`_eq`) and the ORE `ob` (`_ord` / `_ord_ore`) paths — credential-free, no fresh
+test-time encryption.
+
 [overload]: ../../../src/property.rs
 
 ### e2e — oracle over fresh end-to-end encryption
@@ -73,9 +85,12 @@ Defence in depth over the fixture suite: the fixtures are encrypted once at
 `test:sqlx:prep`, so they pin behaviour against a *frozen* ciphertext snapshot;
 the e2e suite re-encrypts on **every run**, so it catches a live crypto-path
 regression (a `cipherstash-client` / ZeroKMS change) that leaves the committed
-fixtures untouched. The e2e suite is also the one that exercises "same plaintext,
-*different* ciphertext" (equality across independently-encrypted values), via the
-fresh duplicate plaintexts it appends each run.
+fixtures untouched. The e2e suite also exercises "same plaintext, *different*
+ciphertext" (equality across independently-encrypted values) via the fresh
+duplicate plaintexts it appends each run — but the fixture suite already covers
+that case credential-free through the committed per-type *doubles* tables
+(`cross_ciphertext.rs`), so the e2e run is defence in depth on it, not the only
+home for it.
 
 ## The shared oracle engine
 
@@ -129,11 +144,13 @@ encryption to reach inputs the fixtures can't.
   fine). [`match_smoke.rs`](./match_smoke.rs) is a plain `#[sqlx::test]` (not
   proptest-driven), loading the fixtures into its own isolated DB.
 - **Equality-true must actually fire.** Random distinct plaintexts almost never
-  collide, so the e2e suite injects deliberate duplicate plaintexts (plus signed
-  extremes and zero) each run to exercise the `a == b ⇒ eq` branch across
-  *distinct* ciphertexts. The fixture suite's curated rows have unique plaintexts,
-  so it exercises the equality-true branch on self-pairs (same ciphertext); the
-  cross-ciphertext case is the e2e suite's job.
+  collide, so both DB suites inject deliberate duplicate plaintexts to exercise
+  the `a == b ⇒ eq` branch across *distinct* ciphertexts: the fixture suite via
+  the committed per-type *doubles* tables (`cross_ciphertext.rs`), and the e2e
+  suite via fresh duplicates (plus signed extremes and zero) each run. The
+  matrix's own curated rows have unique plaintexts, so they exercise the
+  equality-true branch only on self-pairs (same ciphertext) — which is why the
+  doubles tables exist.
 
 ## Running
 
@@ -144,7 +161,7 @@ cargo test -p eql-scalars proptest_invariants
 # fixture + edge-case suites (needs a prepared DB)
 mise run test:sqlx:prep
 cd tests/sqlx && cargo test --test encrypted_domain \
-  property::fixture_oracle property::match_smoke property::edge_cases
+  property::fixture_oracle property::cross_ciphertext property::match_smoke property::edge_cases
 
 # all suites incl. e2e (needs DB + CS_* creds)
 mise run test:sqlx   # enables --features proptest-e2e