Add EQL v3 Drizzle support

.changeset/eql-v3-bigint.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/stack': minor
+---
+
+Re-enable the EQL v3 bigint domain family now that native bigint round-tripping landed in `@cipherstash/protect-ffi` 0.28. Adds the `types.Bigint` / `types.BigintEq` / `types.BigintOrd` / `types.BigintOrdOre` factories (concrete Postgres domains `eql_v3.int8`, `eql_v3.int8_eq`, `eql_v3.int8_ord`, `eql_v3.int8_ord_ore`), their `EncryptedBigint*Column` classes, and full test-matrix + Drizzle operator coverage. Bigint columns take and decrypt to a JS `bigint`; i64 bounds (`-2^63 … 2^63 - 1`) are enforced at the protect-ffi boundary.

.changeset/eql-v3-drizzle.md

@@ -0,0 +1,17 @@
+---
+"@cipherstash/stack": minor
+---
+
+Add EQL v3 Drizzle support at `@cipherstash/stack/eql/v3/drizzle`. A Drizzle-native
+`types` namespace (same PascalCase names as `@cipherstash/stack/eql/v3`) declares
+encrypted columns whose Postgres type is the semantic `eql_v3.<domain>`; the concrete
+type drives the legal query operators. `createEncryptionOperatorsV3` provides
+capability-checked `eq`/`ne`/`gt`/`gte`/`lt`/`lte`/`between`/`contains`/`inArray`/
+`asc`/`desc`/`and`/`or` that emit the latest two-argument `eql_v3` SQL functions with
+full-envelope operands, and
+`extractEncryptionSchemaV3` rebuilds the schema for `EncryptionV3`. The existing v2
+`@cipherstash/stack/drizzle` integration is unchanged.
+
+The v3 text-search helper is `contains`; obsolete `like`/`ilike` helpers are not
+exposed because v3 free-text search is token containment rather than SQL wildcard
+matching.

.changeset/eql-v3-ffi-0-28-concrete-types.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/stack': minor
+---
+
+Upgrade `@cipherstash/protect-ffi` to 0.28.0 and update EQL v3 concrete Postgres domain names to match the SQL fixture (`integer*`, `smallint*`, `bool`, `real*`, and `double*`). The public factories remain semantic (`Integer`, `Smallint`, `Boolean`, `Real`, `Double`) while their concrete domains change, so this is a minor release.

.changeset/eql-v3-text-search.md

@@ -0,0 +1,18 @@
+---
+"@cipherstash/stack": minor
+---
+
+Add the EQL v3 `text_search` authoring DSL on a new `@cipherstash/stack/eql/v3`
+subpath (`types.TextSearch`, v3 `encryptedTable` / `buildEncryptConfig`). The v3
+builders emit the existing `EncryptConfig` shape, so encryption, payloads, and
+query paths are unchanged at runtime.
+
+Also widens the public client types (`EncryptionClientConfig.schemas`,
+`EncryptOptions`, `SearchTerm`/`EncryptQueryOptions`) to a structural contract so
+both v2 and v3 builders are accepted by `Encryption` / `encrypt` / `decrypt` /
+`encryptQuery`. This is a backward-compatible widening — existing v2 usage is
+unaffected. The structural contracts themselves (`BuildableColumn`,
+`BuildableQueryColumn`, `BuildableV3QueryableColumn`, `BuildableTable`,
+`BuildableTableColumns`) and the `encryptModel` return-type mapper
+(`EncryptedFromBuildableTable`) are exported from `@cipherstash/stack/types` so
+consumers can name them.

.changeset/eql-v3-typed-client.md

@@ -0,0 +1,29 @@
+---
+"@cipherstash/stack": minor
+---
+
+Add a strongly-typed EQL v3 client surface on a new `@cipherstash/stack/v3`
+subpath (`EncryptionV3`, `typedClient`, `TypedEncryptionClient`). It re-exports
+the v3 `types` namespace and table API (from `@cipherstash/stack/eql/v3`), so a
+single import provides everything needed to author and use a v3 schema.
+
+Every method derives its types from the concrete `table` / `column` builder
+arguments:
+
+- `encrypt` / `encryptQuery` pin the plaintext to the column's domain type
+  (`text → string`, `timestamp → Date`, …).
+- `encryptQuery` constrains `queryType` to the column's capabilities and rejects
+  storage-only columns at compile time.
+- `encryptModel` / `bulkEncryptModels` validate schema-column fields against their
+  inferred plaintext type (passthrough fields are untouched) and return a precise
+  encrypted model.
+- `decryptModel` / `bulkDecryptModels` return the precise plaintext model,
+  reconstructing `Date` values from the encrypt-config `cast_as`.
+
+Because the typed methods bind to the concrete branded v3 classes, a hand-rolled
+structural table/column is rejected — closing the soundness gap where a non-branded
+table could be encrypted at runtime while typed as plaintext.
+
+Runtime behaviour is unchanged: the encrypt/query paths return the same operations
+as the base client; only the model-decrypt paths add a per-column `Date`
+reconstruction step. The v2 client surface (`Encryption`) is untouched.

.changeset/eql-v3-typed-schema.md

@@ -0,0 +1,7 @@
+---
+'@cipherstash/stack': minor
+---
+
+Add EQL v3 schema builders for supported generated SQL domains under `@cipherstash/stack/eql/v3`, exposed as the `types` namespace (one member per supported EQL v3 domain, e.g. `types.TextEq` / `types.IntegerOrd` / `types.Timestamp`), including explicit query capability metadata (`getQueryCapabilities()` / `isQueryable()`) and v3 table support in model encryption helpers (`encryptModel` / `bulkEncryptModels`).
+
+Also widen the accepted plaintext input type for `encrypt` / `encryptQuery` to include `Date` (via the new `Plaintext` type), so v3 `date` / `timestamp` domains can be encrypted and queried with their natural JavaScript values.

.github/workflows/fta-v3.yml

@@ -0,0 +1,65 @@
+name: "FTA Complexity (EQL v3)"
+
+# Blocking complexity gate for the EQL v3 text-search schema. Runs the Fast
+# TypeScript Analyzer (fta-cli) against the v3 source directory only and fails
+# the check when any file exceeds the score cap (`--score-cap` in the
+# `analyze:complexity` script). FTA is pure static source analysis, so this job
+# needs no build step, database, or credentials.
+
+on:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - 'packages/stack/src/eql/v3/**'
+      # Shared match-index defaults live outside src/eql/v3 but shape every
+      # emitted v3 match block (load-bearing `k`/`m` ciphertext params), so edits
+      # here must trigger the v3 gate too.
+      - 'packages/stack/src/schema/match-defaults.ts'
+      - 'packages/stack/package.json'
+      - '.github/workflows/fta-v3.yml'
+  pull_request:
+    branches:
+      - "**"
+    paths:
+      - 'packages/stack/src/eql/v3/**'
+      - 'packages/stack/src/schema/match-defaults.ts'
+      - 'packages/stack/package.json'
+      - '.github/workflows/fta-v3.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  fta:
+    name: Analyze v3 complexity
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6.0.8
+        name: Install pnpm
+        with:
+          run_install: false
+
+      - name: Install Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      # node-pty's install hook falls back to `node-gyp rebuild` when no
+      # linux-x64 prebuild matches. pnpm/action-setup v6 no longer ships
+      # node-gyp on PATH, so install it explicitly.
+      - name: Install node-gyp
+        run: npm install -g node-gyp
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Non-zero exit (score above the cap) fails the check — this is the
+      # blocking gate. No `continue-on-error`.
+      - name: Analyze v3 complexity
+        run: pnpm --filter @cipherstash/stack run analyze:complexity

.github/workflows/tests.yml

@@ -59,6 +59,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Type tests (stack)
+        run: pnpm --filter @cipherstash/stack run test:types
+
       - name: Lint — no hardcoded package-manager runners
         run: pnpm run lint:runners
 
@@ -82,6 +85,11 @@ jobs:
           echo "CS_CLIENT_KEY=${{ secrets.CS_CLIENT_KEY }}" >> ./packages/stack/.env
           echo "CS_CLIENT_ACCESS_KEY=${{ secrets.CS_CLIENT_ACCESS_KEY }}" >> ./packages/stack/.env
           echo "DATABASE_URL=postgres://cipherstash:password@localhost:5432/cipherstash" >> ./packages/stack/.env
+          # Fail loudly if the live suites would silently skip (missing creds):
+          # the skip-guard in __tests__/live-gate-required.test.ts asserts the
+          # live gates are actually enabled when these are set.
+          echo "REQUIRE_LIVE=1" >> ./packages/stack/.env
+          echo "REQUIRE_LIVE_PG=1" >> ./packages/stack/.env
 
       - name: Create .env file in ./packages/protect-dynamodb/
         run: |
@@ -157,7 +165,7 @@ jobs:
         run: pnpm exec turbo run test:e2e --filter @cipherstash/e2e
 
   # Verifies @cipherstash/stack/wasm-inline works under Deno — i.e. the
-  # WASM build of protect-ffi 0.25+ and auth 0.38+ can round-trip an
+  # WASM build of protect-ffi 0.26+ and auth 0.40+ can round-trip an
   # encryption against ZeroKMS / CTS in a runtime with no native
   # bindings available. The deno.json deliberately omits --allow-ffi so
   # a silent fallback to the NAPI module is impossible.
@@ -294,6 +302,11 @@ jobs:
           echo "CS_CLIENT_KEY=${{ secrets.CS_CLIENT_KEY }}" >> ./packages/stack/.env
           echo "CS_CLIENT_ACCESS_KEY=${{ secrets.CS_CLIENT_ACCESS_KEY }}" >> ./packages/stack/.env
           echo "DATABASE_URL=postgres://cipherstash:password@localhost:5432/cipherstash" >> ./packages/stack/.env
+          # Fail loudly if the live suites would silently skip (missing creds):
+          # the skip-guard in __tests__/live-gate-required.test.ts asserts the
+          # live gates are actually enabled when these are set.
+          echo "REQUIRE_LIVE=1" >> ./packages/stack/.env
+          echo "REQUIRE_LIVE_PG=1" >> ./packages/stack/.env
 
       - name: Create .env file in ./packages/protect-dynamodb/
         run: |

docs/query-api-walkthrough.md

@@ -0,0 +1,77 @@
+# Query API Walkthrough — API → FFI → CipherStash Client
+
+How a query value travels from the public API down to the Rust SDK across the FFI boundary. Terse by design.
+
+## Flow
+
+```mermaid
+flowchart TD
+    subgraph JS["@cipherstash/stack (TypeScript)"]
+        A["User query builder<br/>ops.eq / Supabase filter / client.encryptQuery()"]
+        B["EncryptionClient.encryptQuery(value | terms[])<br/>encryption/index.ts:259"]
+        C["EncryptQueryOperation.execute()<br/>BatchEncryptQueryOperation.execute()"]
+        D["resolveIndexType() + queryTypeToFfi/QueryOp<br/>build QueryPayload{plaintext,column,table,indexType,queryOp}"]
+        E["validate: validateNumericValue<br/>assertValueIndexCompatibility"]
+    end
+
+    subgraph FFI["@cipherstash/protect-ffi (Neon bindings)"]
+        F["JS wrapper encryptQuery / encryptQueryBulk<br/>lib/index.cjs:155"]
+        G["native handle via @neon-rs/load<br/>lib/load.cjs:9"]
+        H["platform .node addon<br/>protect-ffi-darwin-arm64/index.node"]
+    end
+
+    subgraph RUST["CipherStash Client (Rust SDK)"]
+        I["EQL term generation<br/>ORE / match / unique / ste_vec"]
+        J["ZeroKMS key ops"]
+    end
+
+    A --> B --> C --> E --> D --> F --> G --> H --> I
+    I --> J
+    I -- "Encrypted | EncryptedQuery" --> F
+    F -- "formatEncryptedResult()" --> C
+    C -- "SQL/PostgREST WHERE clause" --> A
+```
+
+## Layers
+
+| # | Layer | Entry point | Role |
+|---|-------|-------------|------|
+| 1 | Public API | `encryption/index.ts:259/270` `encryptQuery()` | Overloaded: single value → `EncryptQueryOperation`; `ScalarQueryTerm[]` → `BatchEncryptQueryOperation`. |
+| 1a | Query builders | `drizzle/operators.ts:976`, `supabase/query-builder.ts:44` | `eq/gt/...` operators & deferred builders that batch-encrypt RHS values, then emit a WHERE clause. |
+| 2 | Operations | `operations/encrypt-query.ts:41`, `operations/batch-encrypt-query.ts:115` | `execute()`: validate → resolve index → call FFI. `*WithLockContext` resolves `LockContextInput` via `resolveLockContext` before the FFI call. |
+| 3 | EQL resolution | `helpers/infer-index-type.ts:89`, `types.ts:292` | `resolveIndexType` + `queryTypeToFfi`/`queryTypeToQueryOp` map public `QueryTypeName` → FFI `indexType`/`queryOp`. |
+| 4 | FFI JS wrapper | `protect-ffi/lib/index.cjs:155` | `encryptQuery`/`encryptQueryBulk` → `wrapAsync(native.*)`. |
+| 5 | Native loader | `protect-ffi/lib/load.cjs:9` | `@neon-rs/load` proxies to the platform prebuilt `.node`. |
+| 6 | Rust SDK | compiled into `.node` | CipherStash Client: encryption, EQL/ORE/STE-vec term gen, ZeroKMS. Not a JS dep — shipped inside the addon. |
+
+## Query-type mapping (Layer 3)
+
+```mermaid
+flowchart LR
+    subgraph Public["QueryTypeName"]
+        eq[equality]
+        ord[orderAndRange]
+        txt[freeTextSearch]
+        sel[steVecSelector]
+        trm[steVecTerm]
+    end
+    subgraph FFI["indexType / queryOp"]
+        u[unique]
+        o[ore]
+        m[match]
+        sv[ste_vec]
+    end
+    eq --> u
+    ord --> o
+    txt --> m
+    sel --> sv
+    trm --> sv
+```
+
+## Notes
+
+- **Client init:** `EncryptionClient.init()` (`encryption/index.ts:81`) calls FFI `newClient()` once; the returned `Client` handle is passed into every `encryptQuery` call.
+- **`cipherstashclient`** = the CipherStash Client **Rust SDK**, compiled via Neon into the platform `.node` binary inside `@cipherstash/protect-ffi`. It performs the actual crypto and talks to ZeroKMS.
+- **Result shape:** `EncryptedQueryResult` (`types.ts:175`); shaped by `formatEncryptedResult(..., returnType)` (`eql` vs raw).
+- **Version:** `package.json` pins `@cipherstash/protect-ffi@0.27.0` for the current EQL v3 semantic-domain bundle.
+- `packages/protect/src/ffi/*` mirrors this flow under the older `protect` package name.