Merge eql_v3 into main for the 3.0.0 release

.changeset/README.md

@@ -0,0 +1,25 @@
+# Changesets
+
+This directory drives EQL's release versioning. `@cipherstash/eql`'s version is
+the **single source of truth** for the whole EQL release identity `V`: the SQL
+surface (`eql-V`), the Rust crate (`eql-bindings-vV`), and the npm package
+(`@cipherstash/eql@V`) are all released at `V`, derived from the version
+changesets computes here (see `scripts/sync-lockstep-versions.mjs`).
+
+Because SQL, the crate, and npm are generated from one catalog at one commit,
+**every releasable change needs a changeset** — including SQL-only or crate-only
+changes — so that `V` moves for all three.
+
+Add one with `pnpm changeset`, or hand-write a `.changeset/<name>.md`:
+
+```md
+---
+'@cipherstash/eql': minor   # patch | minor | major
+---
+
+User-facing description of what changed and why.
+```
+
+Prereleases (alpha/beta/rc) use changesets pre-mode; see
+`docs/development/releasing.md`. See
+https://github.com/changesets/changesets for the tool docs.

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.3/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/eql-239-2.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**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))

.changeset/eql-239-3.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': patch
+---
+
+**`=` / `<>` on `eql_v2.ore_block_u64_8_256` now declare a `COMMUTATOR`, so equality joins over the ORE term no longer raise.** Both operators set `COMMUTATOR` to themselves (equality and inequality are symmetric, so each is its own commutator). Why: without it the planner raised `could not find commutator for operator` the first time an `ore_block_u64_8_256` equality was used as a join / mergejoin qualifier (e.g. via the inlined `eql_v3.integer_ord_ore` equality wrappers, since the operators carry `MERGES`). This only enables previously-erroring join plans — it cannot change which rows match or their ordering. ([#239](https://github.com/cipherstash/encrypt-query-language/pull/239))

.changeset/eql-239.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`eql_v3` encrypted-domain schema, with the `integer` family as its first member.** Encrypted-domain type families now live in a new, additional `eql_v3` schema (the existing `eql_v2` schema is unchanged — it keeps the core types/operators and stays the documented public API). Four jsonb-backed domains for encrypted `integer` columns: `eql_v3.integer` (storage-only), `eql_v3.integer_eq` (`=` / `<>` via HMAC), and `eql_v3.integer_ord` / `eql_v3.integer_ord_ore` (also `<` `<=` `>` `>=` via ORE block terms). Supported comparisons resolve to inlinable wrappers; the native `jsonb` operator surface reachable through domain fallback is blocked (raises rather than silently mis-resolving). Each domain's `CHECK` requires the EQL envelope (`v`, `i`), the ciphertext (`c`), and the variant's index term(s), and pins the payload version (`VALUE->>'v' = '2'`, matching `eql_v2._encrypted_check_v`) — so a missing key or wrong-version payload is rejected on insert or cast rather than surfacing later at query time. Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` extractors, not an operator class on the domain. The extractors return the searchable-encrypted-metadata index-term types `eql_v3.hmac_256` / `eql_v3.ore_block_256`, which `eql_v3` owns directly (see the self-contained `eql_v3` schema entry below). Why: a type-safe, per-capability encrypted integer column instead of the untyped `eql_v2_encrypted`, namespaced under its own schema. This is the reference scalar implementation for the generated domain family. ([#239](https://github.com/cipherstash/encrypt-query-language/pull/239), supersedes [#225](https://github.com/cipherstash/encrypt-query-language/pull/225))

.changeset/eql-241-2.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': patch
+---
+
+**The `eql_v3` ORE block comparator now orders ciphertexts of any block count, not just 8.** `eql_v3.compare_ore_block_256_term` derives the block count `N` from the term length (`octet_length = 49·N + 16`) instead of hardcoding 8, so encrypted types whose native ORE width exceeds 8 blocks — `numeric` (14) and `timestamp` (12) — order, range-query, `ORDER BY`, and `MIN`/`MAX` correctly instead of silently mis-ordering. Malformed terms (length not `49·N + 16` for `N ≥ 1`) now raise instead of returning a bogus comparison. The self-contained `eql_v3` SEM type was renamed `eql_v3.ore_block_u64_8_256 → eql_v3.ore_block_256` to reflect that it is width-agnostic (the `eql_v2` type is unchanged). No effect on existing 8-block types (a no-op for `N = 8`). ([#241](https://github.com/cipherstash/encrypt-query-language/issues/241), [#276](https://github.com/cipherstash/encrypt-query-language/pull/276))

.changeset/eql-241.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`eql_v3.numeric` encrypted-domain type family (ordered).** Four jsonb-backed domains for encrypted `numeric` / `decimal` columns — `eql_v3.numeric` (storage-only), `eql_v3.numeric_eq` (`=` / `<>` via HMAC), and `eql_v3.numeric_ord` / `eql_v3.numeric_ord_ore` (also `<` `<=` `>` `>=`, `MIN` / `MAX` via 14-block ORE) — generated from the `numeric` row in `eql-scalars::CATALOG`. cipherstash encrypts `Plaintext::Decimal` at native 14-block ORE width; ordering matches `rust_decimal::Decimal` ordering exactly (equivalent scales such as `1` and `1.0` collide, like Postgres `numeric`). Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` extractors. Why: a type-safe, ordered encrypted decimal column, the first scalar to exercise an ORE term wider than 8 blocks. ([#241](https://github.com/cipherstash/encrypt-query-language/issues/241), [#276](https://github.com/cipherstash/encrypt-query-language/pull/276))

.changeset/eql-243.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`eql_v3.smallint` encrypted-domain type family.** Four jsonb-backed domains for encrypted `smallint` columns — `eql_v3.smallint` (storage-only), `eql_v3.smallint_eq` (`=` / `<>` via HMAC), and `eql_v3.smallint_ord` / `eql_v3.smallint_ord_ore` (also `<` `<=` `>` `>=` via ORE block terms, with `MIN` / `MAX` aggregates) — generated from the `smallint` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.integer` reference. Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` extractors, not an operator class on the domain. Why: a type-safe, per-capability encrypted `smallint` column, proving the scalar generator generalizes beyond the `integer` reference. ([#243](https://github.com/cipherstash/encrypt-query-language/pull/243))

.changeset/eql-252.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**Scalar encrypted-domain types are now defined in a Rust catalog, not TOML manifests; the Python codegen toolchain is removed.** Adding a scalar encrypted-domain type (`integer`, `bigint`, …) is now one row in `eql-scalars::CATALOG` (`crates/eql-scalars/src/lib.rs`) instead of authoring `tasks/codegen/types/<T>.toml`. `mise run build` regenerates the gitignored SQL surface via `cargo run -p eql-codegen` (Rust, std-only) rather than the Python generator. The catalog row's `Fixture` list is the single source of truth for that type's plaintext fixtures: the SQLx test matrix reads it directly as a compile-time-materialised const (`eql_scalars::INT4_VALUES` / `INT2_VALUES`, `ScalarType::FIXTURE_VALUES`), so there is no longer a generated, committed `tests/sqlx/src/fixtures/<T>_values.rs` — a Rust source of truth no longer round-trips through generated Rust. The shipped SQL is unchanged — `release/*.sql` is byte-identical across the cutover — so there is no change for callers installing EQL; this only affects contributors who extend the scalar domain families. The `python` mise tool, the `pytest`-based `test:codegen` (now `cargo test -p eql-scalars -p eql-codegen`), the per-type `mise run codegen:domain` tasks, and the per-type `tests/sqlx/snapshots/<T>_matrix_tests.txt` baselines (collapsed into one catalog-reconciled `tests/sqlx/snapshots/matrix_tests.txt`) are gone. Why: a single compiler-validated source of truth shared by the generator and the SQLx test harness, and one fewer toolchain in the build/test path — building and testing EQL no longer needs Python (Python remains only for the separate docs-markdown tooling). ([#252](https://github.com/cipherstash/encrypt-query-language/pull/252))

.changeset/eql-253.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`eql_v3.bigint` encrypted-domain type family.** Four jsonb-backed domains for encrypted `bigint` columns — `eql_v3.bigint` (storage-only), `eql_v3.bigint_eq` (`=` / `<>` via HMAC), and `eql_v3.bigint_ord` / `eql_v3.bigint_ord_ore` (also `<` `<=` `>` `>=` via ORE block terms, with `MIN` / `MAX` aggregates) — generated from the `bigint` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.integer` reference. Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` extractors, not an operator class on the domain. Why: a type-safe, per-capability encrypted `bigint` column, extending the scalar generator across the full 64-bit integer width. ([#253](https://github.com/cipherstash/encrypt-query-language/pull/253))

.changeset/eql-255.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**Self-contained `eql_v3` schema + standalone `release/cipherstash-encrypt.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.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))

.changeset/eql-256.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`eql_v3.date` encrypted-domain type family.** Four jsonb-backed domains for encrypted `date` columns — `eql_v3.date` (storage-only), `eql_v3.date_eq` (`=` / `<>` via HMAC), and `eql_v3.date_ord` / `eql_v3.date_ord_ore` (also `<` `<=` `>` `>=` via ORE block terms, with `MIN` / `MAX` aggregates) — generated from the `date` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.integer` reference. Plaintexts encrypt under the `date` cast and compare via the same ORE block terms as the integer scalars (ORE is plaintext-agnostic — dates order like integers). Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` extractors, not an operator class on the domain. Why: the first **non-integer ordered** scalar encrypted-domain type — a type-safe, per-capability encrypted `date` column — proving the generator and SQLx test matrix generalize beyond fixed-width integers. ([#256](https://github.com/cipherstash/encrypt-query-language/pull/256))

.changeset/eql-257.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`eql_v3.timestamp` encrypted-domain type family (ordered).** Four jsonb-backed domains for encrypted `timestamp` columns — `eql_v3.timestamp` (storage-only), `eql_v3.timestamp_eq` (`=` / `<>` via HMAC), and `eql_v3.timestamp_ord` / `eql_v3.timestamp_ord_ore` (also `<` `<=` `>` `>=`, `MIN` / `MAX` via 12-block ORE) — generated from the `timestamp` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.date` family. Values are **UTC-normalized** (cipherstash has no timezone-preserving type): plaintexts encrypt under the `timestamp` cast, so the stored value is a UTC instant (Postgres `timestamp with time zone`) wearing the SQL-standard name `timestamp` to match the cipherstash cast / `ColumnType::Timestamp` / `Plaintext::Timestamp` convention. Ordering works because the `eql_v3` ORE block comparator now derives its block count from the ciphertext width (see the comparator entry below) instead of assuming 8. Index via a functional index on the `eql_v3.eq_term` / `eql_v3.ord_term` extractors, not an operator class on the domain. ([#257](https://github.com/cipherstash/encrypt-query-language/pull/257))

.changeset/eql-260.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`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.integer` 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))

.changeset/eql-262.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': patch
+---
+
+**An empty ORE term (`ob: []`) is now rejected by the ORE-bearing `eql_v3` domains instead of silently corrupting ordered queries.** Encrypting the empty string `""` as ordered text produces an empty ORE term (`ob: []`) — the only value that does — and previously an `""` row silently dropped out of `ORDER BY`, was wrongly returned by `eql_v3.max`, and threw off range-query counts (the `eql_v3.ore_block_256` extractor collapsed `ob: []` to NULL index terms). The ORE-bearing domains (`_ord` / `_ord_ore`, and text `_search`) now carry a `CHECK` requiring `ob` to be a non-empty array, so casting or inserting an empty-`ob` payload into an ordered column fails loudly with a check violation (SQLSTATE `23514`) rather than producing an unorderable row. This affects only the empty string in an ordered column: every non-empty string and every fixed-width scalar (int / date / numeric / float) always produces a non-empty `ob`. Storage and equality are unaffected — `""` can still be encrypted into a storage-only (`eql_v3.text`) or equality (`eql_v3.text_eq`) column with a real ciphertext (`c`) and HMAC (`hm`). As defense-in-depth for any path that bypasses the domain (e.g. a comparator composite built directly), the comparator also orders a zero-term ORE composite before every non-empty value (empty sorts first); a genuine SQL `NULL` row is unchanged and keeps standard `NULLS FIRST` / `NULLS LAST` semantics (the extractor is `STRICT`). ([#262](https://github.com/cipherstash/encrypt-query-language/issues/262))

.changeset/eql-267-2.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/eql': minor
+---
+
+**`eql_v3.min` / `eql_v3.max` aggregates over `eql_v3.jsonb_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))