Merge pull request #535 from cipherstash/feat/eql-v3-text-search-schema

feat(stack,cli): EQL v3 typed schema, typed client, Supabase/Drizzle integrations on eql-3.0.0 + protect-ffi 0.29

Author: coderdan

.changeset/adapter-package-split.md

@@ -0,0 +1,28 @@
+---
+'@cipherstash/stack': minor
+'@cipherstash/stack-drizzle': minor
+'@cipherstash/stack-supabase': minor
+---
+
+Split the Drizzle and Supabase integrations into their own packages.
+
+The adapters now ship as first-party packages that depend on `@cipherstash/stack`,
+following the `@cipherstash/prisma-next` precedent:
+
+- **`@cipherstash/stack-drizzle`** — Drizzle ORM integration. EQL v2 on the package
+  root (`@cipherstash/stack-drizzle`: `encryptedType`, `extractEncryptionSchema`,
+  `createEncryptionOperators`) and EQL v3 on `@cipherstash/stack-drizzle/v3`
+  (`types` factories, `createEncryptionOperatorsV3`, `extractEncryptionSchemaV3`, …).
+- **`@cipherstash/stack-supabase`** — Supabase integration: `encryptedSupabase` (v2)
+  and `encryptedSupabaseV3` (v3, connect-time introspection).
+
+**Breaking (`@cipherstash/stack`):** the `./drizzle`, `./supabase`, and
+`./eql/v3/drizzle` subpath exports are removed. Migrate imports:
+
+- `@cipherstash/stack/drizzle` → `@cipherstash/stack-drizzle`
+- `@cipherstash/stack/eql/v3/drizzle` → `@cipherstash/stack-drizzle/v3`
+- `@cipherstash/stack/supabase` → `@cipherstash/stack-supabase`
+
+Add the relevant package to your dependencies alongside `@cipherstash/stack`. A new
+`@cipherstash/stack/adapter-kit` subpath exposes the narrow core internals the
+first-party adapters consume; it is the core↔adapter seam, not general-purpose API.

.changeset/adapter-split-skills.md

@@ -0,0 +1,11 @@
+---
+'stash': patch
+---
+
+Update the bundled `stash-drizzle`, `stash-supabase`, and `stash-encryption` agent
+skills (and the stack README / Supabase reference doc) for the adapter package
+split: the Drizzle and Supabase integrations import from `@cipherstash/stack-drizzle`
+(+ `/v3`) and `@cipherstash/stack-supabase` respectively, installed alongside
+`@cipherstash/stack`, rather than from `@cipherstash/stack/{drizzle,supabase,eql/v3/drizzle}`
+subpaths. Skills ship inside the `stash` tarball, so the stale import paths would
+otherwise become wrong guidance in a user's project.

.changeset/cli-eql-v3-single-bundle.md

@@ -0,0 +1,16 @@
+---
+'stash': minor
+---
+
+`stash eql install --eql-version 3` now installs the eql-3.0.0 GA bundle,
+vendored from the pinned `@cipherstash/eql` package (sha256-verified).
+
+Since eql-3.0.0 one artifact installs everywhere: the operator-class
+statements self-skip when the role lacks superuser (managed Postgres,
+Supabase) and the bundle disables the ORE-backed encrypted domains it cannot
+support. The separate v3 Supabase bundle variant is gone — `--supabase` and
+`--exclude-operator-family` no longer select a different v3 file (the role
+GRANTs for `eql_v3` / `eql_v3_internal` still apply with `--supabase`).
+
+The bundled skills are also refreshed for the eql-3.0.0 naming convention
+(`public.eql_v3_<name>` column domains) and the EQL v3 typed-schema surface.

.changeset/eql-v3-adapter-type-robustness.md

@@ -0,0 +1,38 @@
+---
+'@cipherstash/stack': minor
+---
+
+Restore the EQL v3 envelope and `Result` types the adapters were erasing.
+
+Both v3 adapters typed their operand-encryption paths as `unknown` and dropped
+the `Result` wrapper, so the query-type encoding and the failure channel were
+invisible to the type system:
+
+- `eql/v3/drizzle/operators.ts` typed the client's `encrypt`/`bulkEncrypt` as
+  returning `unknown`, collapsed the operation's `Result` to
+  `{ data?: unknown; failure?: { message } }`, and cast the bulk response to
+  `Array<{ data: unknown }>`.
+- `supabase/query-builder-v3.ts` returned `Promise<unknown[]>` from
+  `encryptCollectedTerms`, `bulkEncryptGroup` and `encryptGroupPerTerm`, and the
+  base `query-builder.ts` did the same.
+
+These now carry the SDK's real types — `Encrypted` (the storage envelope union,
+which includes every v3 per-domain payload), `BulkEncryptedData`, and
+`EncryptedQueryResult` — threaded through a properly-typed operation surface that
+resolves `Result<T, EncryptionError>`. The Supabase divergence the erasure hid is
+now explicit: the v2 path yields `encryptQuery` composite literals and the v3
+path yields `JSON.stringify`'d envelope strings, and both are `EncryptedQueryResult`.
+
+Bumped `minor`, not `patch`: `createEncryptionOperatorsV3` is a public export
+(`@cipherstash/stack/eql/v3/drizzle`), and tightening its client contract from
+`unknown` to a typed operation surface is a compile-time breaking change — a
+downstream consumer passing a loosely-typed (`unknown`-returning) client double
+will now fail `tsc`. That tightening has teeth: `operators.test-d.ts` pins it
+with a negative type-test asserting an `unknown`-returning `{ encrypt }` double
+is rejected (a positive "correctly-typed double is accepted" assertion cannot
+catch a re-erasure, since a correct value is assignable to `unknown`).
+
+Behaviour is otherwise unchanged, with one addition: the Supabase v3 bulk path
+now rejects a `null` envelope returned by `bulkEncrypt` (the restored
+`Encrypted | null` type makes that arm reachable, and a `null` would otherwise
+be `JSON.stringify`'d to the literal `"null"` and sent as a filter operand).

.changeset/eql-v3-bigint-domains.md

@@ -0,0 +1,11 @@
+---
+'@cipherstash/stack': minor
+---
+
+Add the EQL v3 bigint domain family to the public DSL: `types.Bigint`,
+`types.BigintEq`, `types.BigintOrdOre`, and `types.BigintOrd`, backed by the
+`public.bigint*` concrete domains. Plaintext is a JS `bigint`, round-tripped
+losslessly across the protect-ffi 0.28 boundary (i64 bounds enforced at the
+FFI — out-of-range values surface as encryption errors). Index emission follows
+the numeric rule: `bigint_eq` → unique (hm); `bigint_ord`/`bigint_ord_ore` →
+ore (equality answered via ob).

.changeset/eql-v3-bundle-from-package.md

@@ -0,0 +1,9 @@
+---
+'@cipherstash/stack': patch
+---
+
+Source the EQL v3 install bundle from `@cipherstash/eql@3.0.0-alpha.3` instead of a hand-vendored 43k-line SQL fixture committed to the test tree. The package publishes its SQL and its TypeScript wire types from the same `eql-bindings` commit, so the bundle is now pinned to a released EQL version rather than tracked by convention.
+
+Test-and-tooling only — `@cipherstash/eql` is a `devDependency` and no public API changes.
+
+The staleness check in the v3 install helper now compares `eql_v3.version()` against the pinned release instead of probing for a hand-picked sentinel domain. The previous sentinel (`public.timestamp`) exists in both the old and new bundles, so it would have reported a stale install as current and left the suite silently running the wrong SQL.

.changeset/eql-v3-cli-install.md

@@ -0,0 +1,13 @@
+---
+"stash": minor
+---
+
+Add an EQL v3 install path to `stash eql install` via a new `--eql-version <2|3>`
+flag (default `2`). v3 installs the native concrete-domain schema (`public.*`
+type domains, `eql_v3` operators, `eql_v3_internal` constructors) from bundles
+vendored into `packages/cli/src/sql` by `scripts/build-eql-v3-sql.mjs` (full
+bundle + a Supabase variant with the two superuser-only operator-class chunks
+stripped). v3 currently supports the direct install path only —
+`--drizzle`/`--migration`/`--migrations-dir`/`--latest` are rejected — and the
+installer keys `isInstalled`/version checks and Supabase grants to the `eql_v3`
+schema.

.changeset/eql-v3-drizzle-encrypt-query.md

@@ -0,0 +1,22 @@
+---
+'@cipherstash/stack-drizzle': minor
+'@cipherstash/stack': minor
+---
+
+EQL v3 Drizzle: encrypt every query operand with `encryptQuery`, not `encrypt` (#622).
+
+The v3 Drizzle operators (`eq`/`ne`/`gt`/`gte`/`lt`/`lte`/`between`/`notBetween`/
+`inArray`/`notInArray`/`contains`) previously encrypted their operands with
+`client.encrypt`, producing a full storage envelope (including the ciphertext `c`)
+cast to `::jsonb`. A WHERE-clause operand should be a query *term*, not a value to
+store. Every operator now uses `client.encryptQuery`, which yields a
+ciphertext-free query term cast to the column's `eql_v3.query_<domain>` type — so
+predicates carry no ciphertext and reach the bundle's `(domain, query_<domain>)`
+operator overloads. This unifies the scalar/text operators with the JSON
+containment path (already on `encryptQuery`) and removes the previously-optional
+`encryptQuery` guard: it is now a required capability of the operand client.
+
+`@cipherstash/stack` gains a batch `encryptQuery(terms)` overload on
+`TypedEncryptionClient` (the type `EncryptionV3` returns), mirroring the nominal
+`EncryptionClient`. This is additive — it lets `inArray`/`notInArray` encrypt a
+whole list of query terms in one crossing.

.changeset/eql-v3-drizzle-fail-open-guards.md

@@ -0,0 +1,38 @@
+---
+'@cipherstash/stack': minor
+---
+
+Close two fail-open paths in the EQL v3 Drizzle adapter.
+
+`ops.contains()` now throws `EncryptionOperatorError` for a search term that
+tokenizes to nothing: the empty string, or a term shorter than the match index
+tokenizer's `token_length` (3 by default). Such a term produces an empty bloom
+filter, and `stored_bf @> '{}'` is true for every row — so a user searching
+`"ad"` silently received the entire table. Measured live, the terms `"ad"`,
+`"a"` and `"x"` each returned every seeded row, including one in which `"x"`
+did not appear.
+
+The floor counts Unicode codepoints, matching the tokenizer. A UTF-16 length
+check would wave through an astral-plane term — `"👍👍"` is 4 code units but
+only 2 codepoints, yields no trigram, and matched every row.
+
+**Breaking for callers passing short terms:** `contains()` calls that previously
+returned every row now throw. Terms of 3+ codepoints are unaffected.
+
+`v3FromDriver()` now throws the new `EqlV3CodecError` on a payload that is not
+an EQL envelope, instead of surfacing a raw `SyntaxError` for malformed JSON and
+passing a bare scalar through unchecked — `v3FromDriver('5')` previously returned
+`5` typed as `Encrypted`, which then reached `decrypt` as garbage. The guard
+accepts both scalar envelopes (ciphertext at `c`) and SteVec documents
+(ciphertext at `sv[0].c`). A SteVec's `sv` must be a non-empty array: `sv[0]` is
+the decryption root, so `sv: []` carries a ciphertext key but no ciphertext, and
+is now rejected rather than passed to `decrypt`. `EqlV3CodecError` is exported
+from `@cipherstash/stack/eql/v3/drizzle` so callers can catch it.
+
+Also removes an unreachable branch in `inArray`/`notInArray`, whose empty-list
+guard already throws before it.
+
+Note: the v2 Drizzle adapter's `like`/`ilike` path builds the same bloom filters
+and has the same short-term fail-open. It is **not** fixed here — v2 terms carry
+SQL wildcards, so the floor must be measured against what its tokenizer actually
+receives before the shared guard can be reused. Tracked separately.

.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 `public.<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.