fix(v3): harden ste_vec_entry min/max over oc-less entries; cover blocker/ORE-<> review gaps

#2 (behaviour): eql_v3.min/max on ste_vec_entry now ignore non-orderable
(oc-less) entries instead of letting an oc-less STRICT seed pin a wrong
extremum. ore_cllw(entry) is NULL without an oc term, so the naive
ore_cllw(value) < ore_cllw(state) was NULL whenever the running extremum was
oc-less. The sfuncs skip oc-less candidates and replace an oc-less seed, the
same way the ore_cllw btree NULL-filters such rows. New test
jsonb_entry_int4_aggregate_ignores_oc_less_entries feeds a forged hm-only entry
in the SEED position and asserts the correct orderable extremum.

#3a (coverage): v3_jsonb_blocker_return_types_match_native pins each
jsonb_blocked% function's return type to the native operator it shadows
(#> jsonb, #>> text, -/#-/|| jsonb), and v3_jsonb_blocked_composed_expression_raises
asserts composed exprs resolve and raise 'is not supported' (not 'operator does
not exist') — guarding aa13065's blocker-return-type fix.

#3b (coverage): ore_block_comparison_operators_declare_correct_selectivity (T11)
pins ore_block_u64_8_256 <> to neqsel/neqjoinsel with no HASHES, and = to
eqsel/eqjoinsel/HASHES.

Snapshots: matrix_jsonb_entry_tests 54->55, v3_jsonb_tests 72->74. CHANGELOG:
note oc-less entries are ignored by entry min/max.

Author: tobyhede

CHANGELOG.md

@@ -31,7 +31,7 @@ Each entry that ships in a published release links to the PR that introduced it.
 - **Per-domain `MIN` / `MAX` aggregates for the encrypted-domain family.** `eql_v3.min(eql_v3.<T>_ord)` / `eql_v3.max(eql_v3.<T>_ord)` (and the `_ord_ore` twin) are generated for every ord-capable scalar variant, giving type-safe extrema on domain-typed columns — comparison routes through the variant's `<` / `>` operator (ORE block term, no decryption). The aggregates are declared `PARALLEL = SAFE` with a combine function (the state function itself — min/max are associative), so PostgreSQL can use partial/parallel aggregation on large `GROUP BY` workloads. Why: the new domain types previously had no equivalent of the composite-type aggregates. The existing `eql_v2.min(eql_v2_encrypted)` / `eql_v2.max(eql_v2_encrypted)` aggregates are **retained** and continue to work on `eql_v2_encrypted` columns; the per-domain aggregates are additive and coexist with them. ([#239](https://github.com/cipherstash/encrypt-query-language/pull/239))
 - **`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))
 - **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`. 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.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))
 
 ### Changed
 

src/v3/jsonb/aggregates.sql

@@ -15,16 +15,27 @@
 --! Per the encrypted-domain footgun rules the state functions are
 --! `LANGUAGE plpgsql` with the pinned `search_path` — a `LANGUAGE sql` body would
 --! be inlinable and the planner could elide it.
+--!
+--! @note **Only `oc`-carrying entries are orderable.** `eql_v3.ore_cllw(entry)`
+--!   returns NULL when an entry has no `oc` (CLLW ORE) term — the same entries a
+--!   `eql_v3.ore_cllw` btree NULL-filters from range scans. The state functions
+--!   therefore IGNORE `oc`-less entries (they never become or survive as the
+--!   extremum), so `min`/`max` is well-defined over a mix of `oc`-carrying and
+--!   `oc`-less entries and is not corrupted by an `oc`-less seed. A naive
+--!   `ore_cllw(value) < ore_cllw(state)` would be NULL whenever either side
+--!   lacks `oc`, pinning a wrong (`oc`-less) extremum when the first aggregated
+--!   row is `oc`-less. An all-`oc`-less input has no orderable extremum and
+--!   returns the (arbitrary) STRICT seed.
 
 --! @brief State function for min on eql_v3.ste_vec_entry.
 --!
---! Keeps whichever entry has the lesser CLLW ORE term. STRICT, so NULL entries
---! (and entries whose `oc` is absent, yielding a NULL `ore_cllw`) are skipped by
---! the aggregate machinery / fall through to `state`.
+--! Keeps whichever orderable entry has the lesser CLLW ORE term. STRICT, so SQL
+--! NULL entries are skipped by the aggregate machinery; `oc`-less (non-orderable)
+--! entries are skipped explicitly (see the @note on this file).
 --!
 --! @param state eql_v3.ste_vec_entry Running extremum.
 --! @param value eql_v3.ste_vec_entry Candidate entry.
---! @return eql_v3.ste_vec_entry The lesser of the two by `ore_cllw`.
+--! @return eql_v3.ste_vec_entry The lesser orderable entry by `ore_cllw`.
 CREATE FUNCTION eql_v3.ste_vec_entry_min_sfunc(
   state eql_v3.ste_vec_entry,
   value eql_v3.ste_vec_entry
@@ -33,8 +44,17 @@ RETURNS eql_v3.ste_vec_entry
 LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE
 SET search_path = pg_catalog, extensions, public
 AS $$
+DECLARE
+  value_ore eql_v3.ore_cllw := eql_v3.ore_cllw(value);
+  state_ore eql_v3.ore_cllw := eql_v3.ore_cllw(state);
 BEGIN
-  IF eql_v3.ore_cllw(value) < eql_v3.ore_cllw(state) THEN
+  -- A non-orderable (oc-less) candidate never replaces the running extremum.
+  IF value_ore IS NULL THEN
+    RETURN state;
+  END IF;
+  -- Adopt the candidate when the running extremum is itself non-orderable
+  -- (e.g. an oc-less STRICT seed) or strictly greater.
+  IF state_ore IS NULL OR value_ore < state_ore THEN
     RETURN value;
   END IF;
   RETURN state;
@@ -53,12 +73,12 @@ CREATE AGGREGATE eql_v3.min(eql_v3.ste_vec_entry) (
 
 --! @brief State function for max on eql_v3.ste_vec_entry.
 --!
---! Keeps whichever entry has the greater CLLW ORE term. STRICT, mirroring
---! `ste_vec_entry_min_sfunc`.
+--! Keeps whichever orderable entry has the greater CLLW ORE term. `oc`-less
+--! entries are skipped, mirroring `ste_vec_entry_min_sfunc` (see the file @note).
 --!
 --! @param state eql_v3.ste_vec_entry Running extremum.
 --! @param value eql_v3.ste_vec_entry Candidate entry.
---! @return eql_v3.ste_vec_entry The greater of the two by `ore_cllw`.
+--! @return eql_v3.ste_vec_entry The greater orderable entry by `ore_cllw`.
 CREATE FUNCTION eql_v3.ste_vec_entry_max_sfunc(
   state eql_v3.ste_vec_entry,
   value eql_v3.ste_vec_entry
@@ -67,8 +87,17 @@ RETURNS eql_v3.ste_vec_entry
 LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE
 SET search_path = pg_catalog, extensions, public
 AS $$
+DECLARE
+  value_ore eql_v3.ore_cllw := eql_v3.ore_cllw(value);
+  state_ore eql_v3.ore_cllw := eql_v3.ore_cllw(state);
 BEGIN
-  IF eql_v3.ore_cllw(value) > eql_v3.ore_cllw(state) THEN
+  -- A non-orderable (oc-less) candidate never replaces the running extremum.
+  IF value_ore IS NULL THEN
+    RETURN state;
+  END IF;
+  -- Adopt the candidate when the running extremum is itself non-orderable
+  -- (e.g. an oc-less STRICT seed) or strictly lesser.
+  IF state_ore IS NULL OR value_ore > state_ore THEN
     RETURN value;
   END IF;
   RETURN state;

tests/sqlx/snapshots/matrix_jsonb_entry_tests.txt

@@ -1,3 +1,4 @@
+jsonb_entry::jsonb_entry_<T>_aggregate_ignores_oc_less_entries
 jsonb_entry::jsonb_entry_<T>_fixture_shape
 jsonb_entry::jsonb_entry_<T>_index_engages
 jsonb_entry::jsonb_entry_<T>_ore_cllw_injectivity

tests/sqlx/snapshots/v3_jsonb_tests.txt

@@ -4,6 +4,8 @@ v3_jsonb_arrow_accessors_supported_null
 v3_jsonb_arrow_integer_index_on_array
 v3_jsonb_at_at_blocker
 v3_jsonb_at_question_blocker
+v3_jsonb_blocked_composed_expression_raises
+v3_jsonb_blocker_return_types_match_native
 v3_jsonb_concat_blocker
 v3_jsonb_containment_hm_only
 v3_jsonb_containment_mixed

tests/sqlx/tests/encrypted_domain/family/sem.rs

@@ -546,3 +546,54 @@ async fn has_bloom_filter_detects_bf_presence(pool: PgPool) -> Result<()> {
     }
     Ok(())
 }
+
+/// T11 — Planner-selectivity metadata for the `eql_v3.ore_block_u64_8_256`
+/// `=` / `<>` operators. `<>` must use the inequality estimators
+/// (`neqsel` / `neqjoinsel`) and must NOT declare `HASHES` — an earlier revision
+/// copied `=`'s `eqsel` / `eqjoinsel` + `HASHES` onto `<>`, which is meaningless
+/// (you cannot hash-join on inequality) and mis-estimates selectivity (#267
+/// review / aa13065). `=` is the contrast: it keeps `eqsel` / `eqjoinsel` and
+/// `HASHES`. A catalog pin (deterministic, no plan dependence).
+#[sqlx::test]
+async fn ore_block_comparison_operators_declare_correct_selectivity(pool: PgPool) -> Result<()> {
+    let (eq_rest, eq_join, eq_hashes, eq_merges): (String, String, bool, bool) = sqlx::query_as(
+        r#"
+        SELECT o.oprrest::text, o.oprjoin::text, o.oprcanhash, o.oprcanmerge
+        FROM pg_operator o
+        WHERE o.oprname = '='
+          AND o.oprleft  = 'eql_v3.ore_block_u64_8_256'::regtype
+          AND o.oprright = 'eql_v3.ore_block_u64_8_256'::regtype
+        "#,
+    )
+    .fetch_one(&pool)
+    .await?;
+    assert_eq!(eq_rest, "eqsel", "= must use eqsel");
+    assert_eq!(eq_join, "eqjoinsel", "= must use eqjoinsel");
+    assert!(eq_hashes, "= must declare HASHES");
+    assert!(eq_merges, "= must declare MERGES");
+
+    let (neq_rest, neq_join, neq_hashes): (String, String, bool) = sqlx::query_as(
+        r#"
+        SELECT o.oprrest::text, o.oprjoin::text, o.oprcanhash
+        FROM pg_operator o
+        WHERE o.oprname = '<>'
+          AND o.oprleft  = 'eql_v3.ore_block_u64_8_256'::regtype
+          AND o.oprright = 'eql_v3.ore_block_u64_8_256'::regtype
+        "#,
+    )
+    .fetch_one(&pool)
+    .await?;
+    assert_eq!(
+        neq_rest, "neqsel",
+        "<> must use neqsel (not eqsel — it estimates the inequality fraction)"
+    );
+    assert_eq!(
+        neq_join, "neqjoinsel",
+        "<> must use neqjoinsel (not eqjoinsel)"
+    );
+    assert!(
+        !neq_hashes,
+        "<> must NOT declare HASHES — hash joins are meaningless for inequality"
+    );
+    Ok(())
+}

tests/sqlx/tests/encrypted_domain/jsonb_entry.rs

@@ -211,3 +211,86 @@ async fn jsonb_entry_int4_index_engages(pool: sqlx::PgPool) -> anyhow::Result<()
     tx.commit().await?;
     Ok(())
 }
+
+// ----------------------------------------------------------------------------
+// Aggregate robustness over non-orderable (oc-less) entries. `eql_v3.ore_cllw`
+// is NULL for an entry without an `oc` term, so a naive `ore_cllw(value) <
+// ore_cllw(state)` would be NULL whenever the running extremum is oc-less —
+// pinning a wrong result when the FIRST aggregated row (the STRICT seed) is
+// oc-less. The min/max sfuncs explicitly skip oc-less entries. This feeds a
+// forged hm-only (oc-less) entry in the SEED position alongside real oc-carrying
+// entries and asserts the extremum is the correct ORDERABLE entry, never the
+// oc-less seed. The whole-suite matrix never exercises this (every v3_doc_int4
+// entry carries oc).
+// ----------------------------------------------------------------------------
+#[sqlx::test(fixtures(path = "../../fixtures", scripts("v3_doc_int4")))]
+async fn jsonb_entry_int4_aggregate_ignores_oc_less_entries(
+    pool: sqlx::PgPool,
+) -> anyhow::Result<()> {
+    let sel = SELECTOR;
+    // A valid eql_v3.ste_vec_entry that is NOT orderable: string s, string c,
+    // exactly one of hm/oc — here `hm`, so `eql_v3.ore_cllw(entry)` is NULL.
+    let oc_less = r#"{"s":"forged","c":"x","hm":"00"}"#;
+
+    let mut sorted: Vec<i32> = <JsonbEntryInt4 as ScalarType>::fixture_values()
+        .iter()
+        .map(|e| e.0)
+        .collect();
+    sorted.sort();
+    let low = sorted[0];
+    let high = *sorted.last().expect("fixture is non-empty");
+
+    let mut tx = pool.begin().await?;
+    sqlx::query("CREATE TEMP TABLE oc_mix (value eql_v3.ste_vec_entry) ON COMMIT DROP")
+        .execute(&mut *tx)
+        .await?;
+    // SEED position: the oc-less entry is inserted FIRST, so the STRICT seed is
+    // non-orderable — the exact case the sfunc guard must survive.
+    sqlx::query("INSERT INTO oc_mix(value) VALUES ($1::jsonb::eql_v3.ste_vec_entry)")
+        .bind(oc_less)
+        .execute(&mut *tx)
+        .await?;
+    sqlx::query(&format!(
+        "INSERT INTO oc_mix(value) \
+         SELECT (payload -> '{sel}'::text)::eql_v3.ste_vec_entry \
+         FROM fixtures.v3_doc_int4 WHERE plaintext IN ({low}, {high})",
+    ))
+    .execute(&mut *tx)
+    .await?;
+
+    // Expected extrema: the orderable entries for the smallest / largest int4,
+    // NOT the oc-less seed.
+    let expect_min: String = sqlx::query_scalar(&format!(
+        "SELECT ((payload -> '{sel}'::text)::eql_v3.ste_vec_entry)::text \
+         FROM fixtures.v3_doc_int4 WHERE plaintext = {low}",
+    ))
+    .fetch_one(&mut *tx)
+    .await?;
+    let expect_max: String = sqlx::query_scalar(&format!(
+        "SELECT ((payload -> '{sel}'::text)::eql_v3.ste_vec_entry)::text \
+         FROM fixtures.v3_doc_int4 WHERE plaintext = {high}",
+    ))
+    .fetch_one(&mut *tx)
+    .await?;
+
+    let got_min: String = sqlx::query_scalar("SELECT eql_v3.min(value)::text FROM oc_mix")
+        .fetch_one(&mut *tx)
+        .await?;
+    let got_max: String = sqlx::query_scalar("SELECT eql_v3.max(value)::text FROM oc_mix")
+        .fetch_one(&mut *tx)
+        .await?;
+
+    anyhow::ensure!(
+        got_min == expect_min,
+        "eql_v3.min must ignore the oc-less seed and return the smallest orderable entry;\n  \
+         want {expect_min}\n  got  {got_min}",
+    );
+    anyhow::ensure!(
+        got_max == expect_max,
+        "eql_v3.max must ignore the oc-less entry and return the largest orderable entry;\n  \
+         want {expect_max}\n  got  {got_max}",
+    );
+
+    tx.commit().await?;
+    Ok(())
+}