feat(stack): EQL v3 Drizzle adapter on protect-ffi 0.28 (public.* domains)

Adds the EQL v3 Drizzle integration at @cipherstash/stack/eql/v3/drizzle:
drizzle-native column types, capability-checked operators emitting the
two-argument eql_v3 SQL functions, and schema extraction for EncryptionV3.

Replayed onto feat/eql-v3-bigint-restack, which already provides the FFI
0.28 concrete types, public.* domains, the bigint family, and the
eqlVersion:3 fix. The adapter is namespace-agnostic (domains derived via
getEqlType); tests updated to the base's public.<domain> naming while
operator functions remain eql_v3.*.

Superseded local work (concrete-types/bigint/FFI-0.28 re-vendor, redundant
live guards, parallel matrix overhaul) dropped in favour of the base's
versions. Original granular history retained in
backup/eql-v3-drizzle-concrete-types-pre-ffi028-public-rebase.

Author: tobyhede

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

packages/stack/__tests__/drizzle-v3/codec.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { v3FromDriver, v3ToDriver } from '@/eql/v3/drizzle/codec'
+
+describe('v3 codec', () => {
+  it('serialises an object to a jsonb string', () => {
+    expect(v3ToDriver({ v: 1, c: 'ct' })).toBe('{"v":1,"c":"ct"}')
+  })
+
+  it('maps null/undefined to SQL NULL (JS null), never the JSON null literal', () => {
+    expect(v3ToDriver(null)).toBeNull()
+    expect(v3ToDriver(undefined)).toBeNull()
+  })
+
+  it('parses a jsonb string back to an object', () => {
+    expect(v3FromDriver('{"v":1,"c":"ct"}')).toEqual({ v: 1, c: 'ct' })
+  })
+
+  it('passes an already-parsed object through unchanged', () => {
+    const obj = { v: 1 }
+    expect(v3FromDriver(obj)).toBe(obj)
+  })
+
+  it('passes null/undefined through on read', () => {
+    expect(v3FromDriver(null)).toBeNull()
+    expect(v3FromDriver(undefined)).toBeUndefined()
+  })
+})

packages/stack/__tests__/drizzle-v3/column.test.ts

@@ -0,0 +1,96 @@
+import { pgTable } from 'drizzle-orm/pg-core'
+import { describe, expect, it } from 'vitest'
+import { types as v3Types } from '@/eql/v3'
+import {
+  EQL_V3_DOMAINS,
+  getEqlV3Column,
+  isEqlV3Column,
+  makeEqlV3Column,
+} from '@/eql/v3/drizzle/column'
+import { typedEntries, V3_MATRIX } from '../v3-matrix/catalog'
+
+const slug = (eqlType: string) => eqlType.replace('eql_v3.', '')
+
+describe('makeEqlV3Column', () => {
+  it('sets dataType() to the concrete eql_v3 domain', () => {
+    const col = makeEqlV3Column(v3Types.IntegerOrd('age'))
+    const table = pgTable('users', { age: col })
+
+    expect(table.age.getSQLType()).toBe('public.integer_ord')
+  })
+
+  it('recovers the stashed builder before and after pgTable processing', () => {
+    const col = makeEqlV3Column(v3Types.TextEq('nickname'))
+    expect(isEqlV3Column(col)).toBe(true)
+    expect(getEqlV3Column('nickname', col)?.getEqlType()).toBe('public.text_eq')
+
+    const t = pgTable('users', { nickname: col })
+    expect(getEqlV3Column('nickname', t.nickname)?.getEqlType()).toBe(
+      'public.text_eq',
+    )
+  })
+
+  it('EQL_V3_DOMAINS contains every concrete domain', () => {
+    const all = Object.values(v3Types).map((f) => f('x').getEqlType())
+    for (const domain of all) expect(EQL_V3_DOMAINS.has(domain)).toBe(true)
+  })
+
+  it('isEqlV3Column is false for a plain value', () => {
+    expect(isEqlV3Column({})).toBe(false)
+  })
+
+  it('recognises v3 columns by the Drizzle getSQLType API', () => {
+    expect(
+      isEqlV3Column({
+        getSQLType: () => 'public.text_eq',
+      }),
+    ).toBe(true)
+  })
+
+  it('recovers a v3 builder for columns recognised by getSQLType', () => {
+    const builder = getEqlV3Column('nickname', {
+      getSQLType: () => 'public.text_eq',
+    })
+
+    expect(builder?.getName()).toBe('nickname')
+    expect(builder?.getEqlType()).toBe('public.text_eq')
+  })
+
+  it('recognises v3 columns by dataType() when getSQLType is absent', () => {
+    const column = { dataType: () => 'public.text_eq' }
+    const builder = getEqlV3Column('nickname', column)
+
+    expect(isEqlV3Column(column)).toBe(true)
+    expect(builder?.getName()).toBe('nickname')
+    expect(builder?.getEqlType()).toBe('public.text_eq')
+  })
+
+  it('recognises v3 columns by sqlName when getSQLType is absent', () => {
+    const column = { sqlName: 'public.integer_ord' }
+    const builder = getEqlV3Column('age', column)
+
+    expect(isEqlV3Column(column)).toBe(true)
+    expect(builder?.getName()).toBe('age')
+    expect(builder?.getEqlType()).toBe('public.integer_ord')
+  })
+
+  it.each(
+    typedEntries(V3_MATRIX),
+  )('%s round-trips through makeEqlV3Column and pgTable', (eqlType, spec) => {
+    const columnName = slug(eqlType)
+    const builder = spec.builder(columnName)
+    const column = makeEqlV3Column(builder)
+
+    expect(builder.getEqlType()).toBe(eqlType)
+    expect(builder).toBeInstanceOf(spec.ColumnClass)
+    expect(isEqlV3Column(column)).toBe(true)
+    expect(getEqlV3Column(columnName, column)?.getEqlType()).toBe(eqlType)
+
+    const table = pgTable('users', { [columnName]: column } as never)
+    const pgColumn = (table as Record<string, { getSQLType(): string }>)[
+      columnName
+    ]
+    expect(pgColumn?.getSQLType()).toBe(eqlType)
+    expect(getEqlV3Column(columnName, pgColumn)?.getEqlType()).toBe(eqlType)
+  })
+})

packages/stack/__tests__/drizzle-v3/exports.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import * as barrel from '@/eql/v3/drizzle'
+
+describe('v3 drizzle barrel', () => {
+  it('exports the public surface', () => {
+    expect(typeof barrel.createEncryptionOperatorsV3).toBe('function')
+    expect(typeof barrel.extractEncryptionSchemaV3).toBe('function')
+    expect(typeof barrel.EncryptionOperatorError).toBe('function')
+    expect(typeof barrel.types.TextSearch).toBe('function')
+    expect(barrel.types.IntegerOrd('age')).toBeDefined()
+  })
+})