Merge pull request #257 from cipherstash/v3-domain-type-timestamptz

feat(scalars): add eql_v3.timestamptz encrypted-domain type (equality-only)

Author: tobyhede

CHANGELOG.md

@@ -26,6 +26,7 @@ Each entry that ships in a published release links to the PR that introduced it.
 - **`eql_v3.int2` encrypted-domain type family.** Four jsonb-backed domains for encrypted `int2` columns — `eql_v3.int2` (storage-only), `eql_v3.int2_eq` (`=` / `<>` via HMAC), and `eql_v3.int2_ord` / `eql_v3.int2_ord_ore` (also `<` `<=` `>` `>=` via ORE block terms, with `MIN` / `MAX` aggregates) — generated from the `int2` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.int4` 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 `int4` reference. ([#243](https://github.com/cipherstash/encrypt-query-language/pull/243))
 - **`eql_v3.int8` encrypted-domain type family.** Four jsonb-backed domains for encrypted `int8` columns — `eql_v3.int8` (storage-only), `eql_v3.int8_eq` (`=` / `<>` via HMAC), and `eql_v3.int8_ord` / `eql_v3.int8_ord_ore` (also `<` `<=` `>` `>=` via ORE block terms, with `MIN` / `MAX` aggregates) — generated from the `int8` row in `eql-scalars::CATALOG` by the same materializer as the `eql_v3.int4` 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))
 - **`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.int4` 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))
+- **`eql_v3.timestamptz` encrypted-domain type family (equality-only).** Two jsonb-backed domains for encrypted `timestamptz` columns — `eql_v3.timestamptz` (storage-only) and `eql_v3.timestamptz_eq` (`=` / `<>` via HMAC) — generated from the `timestamptz` 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. Index via a functional index on the `eql_v3.eq_term` extractor, not an operator class on the domain. **Ordering (`<` `<=` `>` `>=`, `MIN` / `MAX`) is deferred:** cipherstash encrypts `Plaintext::Timestamp` at native 12-block ORE width, but EQL's only ORE comparator (`eql_v2.compare_ore_block_u64_8_256_term`) is hardcoded to 8 blocks, so ordered timestamptz domains would silently mis-order. There are no `eql_v3.timestamptz_ord` / `_ord_ore` domains and no timestamptz `MIN` / `MAX` aggregates until a wide-ORE (12-block) term lands — tracked in [#241](https://github.com/cipherstash/encrypt-query-language/issues/241). Why: a type-safe, equality-searchable encrypted UTC-timestamp column, stacking on the `date` temporal-scalar foundation; ordering follows once the comparator supports the native ciphertext width. ([#257](https://github.com/cipherstash/encrypt-query-language/pull/257))
 - **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))
 - **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))
 

crates/eql-scalars/src/fixture.rs

@@ -27,7 +27,11 @@ impl Fixture {
             },
             Fixture::Zero => Some(0),
             Fixture::Int(n) => Some(n),
-            Fixture::Numeric(_) | Fixture::Text(_) | Fixture::Jsonb(_) | Fixture::Date(_) => None,
+            Fixture::Numeric(_)
+            | Fixture::Text(_)
+            | Fixture::Jsonb(_)
+            | Fixture::Date(_)
+            | Fixture::Timestamptz(_) => None,
         }
     }
 
@@ -52,7 +56,11 @@ impl Fixture {
                 .zero_symbol()
                 .to_string(),
             Fixture::Int(n) => n.to_string(),
-            Fixture::Numeric(s) | Fixture::Text(s) | Fixture::Jsonb(s) | Fixture::Date(s) => {
+            Fixture::Numeric(s)
+            | Fixture::Text(s)
+            | Fixture::Jsonb(s)
+            | Fixture::Date(s)
+            | Fixture::Timestamptz(s) => {
                 format!("{s:?}")
             }
         }

crates/eql-scalars/src/kind.rs

@@ -68,7 +68,11 @@ impl ScalarKind {
             ScalarKind::I16 => Some(BoundedIntKind::I16),
             ScalarKind::I32 => Some(BoundedIntKind::I32),
             ScalarKind::I64 => Some(BoundedIntKind::I64),
-            ScalarKind::Numeric | ScalarKind::Text | ScalarKind::Jsonb | ScalarKind::Date => None,
+            ScalarKind::Numeric
+            | ScalarKind::Text
+            | ScalarKind::Jsonb
+            | ScalarKind::Date
+            | ScalarKind::Timestamptz => None,
         }
     }
 
@@ -78,11 +82,11 @@ impl ScalarKind {
         self.as_bounded_int().is_some()
     }
 
-    /// True for chrono-backed temporal kinds (`Date`; `Timestamptz` once added) —
-    /// the kinds whose test `ScalarType` impl is generated by `temporal_values!`
-    /// rather than the integer proc-macro path. Replaces the `[temporal]` marker.
+    /// True for chrono-backed temporal kinds (`Date`, `Timestamptz`) — the kinds
+    /// whose test `ScalarType` impl is generated by `temporal_values!` rather
+    /// than the integer proc-macro path. Replaces the `[temporal]` marker.
     pub const fn is_temporal(self) -> bool {
-        matches!(self, ScalarKind::Date)
+        matches!(self, ScalarKind::Date | ScalarKind::Timestamptz)
     }
 
     /// A debug/identifier string for the kind. For the codegen-supported kinds
@@ -101,6 +105,7 @@ impl ScalarKind {
             ScalarKind::Text => "text",
             ScalarKind::Jsonb => "jsonb",
             ScalarKind::Date => "chrono::NaiveDate",
+            ScalarKind::Timestamptz => "chrono::DateTime<Utc>",
         }
     }
 }

crates/eql-scalars/src/lib.rs

@@ -64,6 +64,13 @@ pub enum ScalarKind {
     /// live on `BoundedIntKind`, which `Date` cannot be, so they are
     /// unreachable for it by construction rather than by a runtime panic.
     Date,
+    /// UTC timestamp (`chrono::DateTime<Utc>`). Ordered like the integer kinds
+    /// via ORE, but string-backed (RFC3339) at the catalog layer and with no
+    /// i128 range — so it is *not* `is_int()` and the bounded-numeric accessors
+    /// panic for it, exactly like the other non-integer kinds. UTC-normalized:
+    /// cipherstash has no tz-preserving type, so it maps to the `timestamp`
+    /// cast and the SQL `timestamp with time zone` plaintext type.
+    Timestamptz,
 }
 
 /// A fixed index term known to the scalar materializer.
@@ -99,6 +106,10 @@ pub enum Fixture {
     /// the string is parsed into a `chrono::NaiveDate` in the SQLx harness, not
     /// here. Distinct by literal, like the other string-backed fixtures.
     Date(&'static str),
+    /// An RFC3339 UTC timestamp string (`"1970-01-01T00:00:00Z"`). The catalog
+    /// stays zero-dep, so the string is parsed into a `chrono::DateTime<Utc>` in
+    /// the SQLx harness, not here. Distinct by literal, like `Date`.
+    Timestamptz(&'static str),
 }
 
 /// One generated public domain: a suffix appended to the type token and the
@@ -140,6 +151,7 @@ macro_rules! fixtures {
     (numeric; $($s:literal),* $(,)?) => { &[$(Fixture::Numeric($s)),*] };
     (jsonb;   $($s:literal),* $(,)?) => { &[$(Fixture::Jsonb($s)),*] };
     (date;    $($s:literal),* $(,)?) => { &[$(Fixture::Date($s)),*] };
+    (timestamptz; $($s:literal),* $(,)?) => { &[$(Fixture::Timestamptz($s)),*] };
 }
 
 /// Domains shared by every ordered-integer scalar, in manifest file order:
@@ -163,6 +175,24 @@ const ORDERED_INT_DOMAINS: &[DomainSpec] = &[
     },
 ];
 
+/// Equality-only domains: storage (no terms) + `_eq` (hm). Used by scalar types
+/// that can hash for equality but cannot (yet) be ordered. `timestamptz` is the
+/// first such type: cipherstash encrypts `Plaintext::Timestamp` at native
+/// 12-block ORE width, but EQL's only ORE comparator
+/// (`eql_v2.compare_ore_block_u64_8_256_term`) is hardcoded to 8 blocks, so an
+/// ordered domain would silently mis-order. Ordering is deferred until a
+/// wide-ORE (12-block) term exists.
+const EQ_ONLY_DOMAINS: &[DomainSpec] = &[
+    DomainSpec {
+        suffix: "",
+        terms: &[],
+    },
+    DomainSpec {
+        suffix: "_eq",
+        terms: &[Term::Hm],
+    },
+];
+
 /// int4 fixture plaintexts.
 /// `N(..)` literals are range-checked against `i32` at compile time.
 const INT4_FIXTURES: &[Fixture] = fixtures!(int i32;
@@ -196,6 +226,21 @@ const DATE_FIXTURES: &[Fixture] = fixtures!(date;
     "2012-06-30", "2016-03-15", "2020-10-21", "2024-02-29", "2038-01-19",
     "2099-12-31");
 
+/// timestamptz fixture plaintexts — RFC3339 UTC strings, parsed into
+/// `chrono::DateTime<Utc>` in the SQLx harness (the catalog stays zero-dep).
+/// The three temporal pivots MUST be present verbatim: `"1900-01-01T00:00:00Z"`
+/// (min_pivot), `"1970-01-01T00:00:00Z"` (zero = `DateTime::<Utc>::default()`,
+/// the Unix epoch), and `"2099-12-31T23:59:59Z"` (max_pivot) — the matrix
+/// fetches each one's ciphertext via `fetch_fixture_payload`, which fails loudly
+/// if a row is absent. The interior timestamps span varied dates AND times of
+/// day so range operators yield distinguishable counts. All distinct.
+const TIMESTAMPTZ_FIXTURES: &[Fixture] = fixtures!(timestamptz;
+    "1900-01-01T00:00:00Z", "1950-07-15T06:30:00Z", "1969-12-31T23:59:59Z",
+    "1970-01-01T00:00:00Z", "1970-01-01T00:00:01Z", "1985-04-12T23:20:50Z",
+    "1999-12-31T23:59:59Z", "2000-01-01T00:00:00Z", "2004-02-29T12:00:00Z",
+    "2012-06-30T11:59:59Z", "2016-03-15T08:15:30Z", "2020-10-21T14:45:00Z",
+    "2024-02-29T17:30:45Z", "2038-01-19T03:14:07Z", "2099-12-31T23:59:59Z");
+
 const INT4: ScalarSpec = ScalarSpec {
     token: "int4",
     kind: ScalarKind::I32,
@@ -232,9 +277,30 @@ pub const DATE: ScalarSpec = ScalarSpec {
     fixtures: DATE_FIXTURES,
 };
 
+/// `timestamptz` — an **equality-only** (UTC-normalized) non-integer scalar.
+/// Uses `EQ_ONLY_DOMAINS` (storage + `_eq`) rather than the four-domain ordered
+/// shape: cipherstash encrypts `Plaintext::Timestamp` at native 12-block ORE
+/// width, but EQL's only ORE comparator
+/// (`eql_v2.compare_ore_block_u64_8_256_term`) is hardcoded to 8 blocks, so an
+/// ordered timestamptz domain would silently mis-order. Ordering is deferred to
+/// a future PR that adds a wide-ORE (12-block) term. The three "pivot" fixture
+/// values are retained as equality pivots; the kind stays ordered-shaped
+/// (carries a rust type, no i128 range) so the harness can parse them.
+///
+/// Public (like `DATE`) because the SQLx harness reads `TIMESTAMPTZ.fixtures`
+/// directly to parse the RFC3339 strings into `chrono::DateTime<Utc>` at
+/// runtime — there is no `TIMESTAMPTZ_VALUES` const (chrono is not
+/// `const`-friendly and `eql-scalars` stays zero-dep).
+pub const TIMESTAMPTZ: ScalarSpec = ScalarSpec {
+    token: "timestamptz",
+    kind: ScalarKind::Timestamptz,
+    domains: EQ_ONLY_DOMAINS,
+    fixtures: TIMESTAMPTZ_FIXTURES,
+};
+
 /// The scalar catalog — the single source of truth. Order is significant (it
 /// drives generation order). New types are appended as their SQL surface lands.
-pub const CATALOG: &[ScalarSpec] = &[INT4, INT2, INT8, DATE];
+pub const CATALOG: &[ScalarSpec] = &[INT4, INT2, INT8, DATE, TIMESTAMPTZ];
 
 /// Materialise an integer scalar's fixtures into a typed `&'static` slice at
 /// compile time. This is the **single-sourced** plaintext list the SQLx test