feat(stack): strongly-typed v3 Drizzle adapter (envelope typing, docs, perf)

- A3: type the Drizzle customType around the stored Encrypted envelope, not
  plaintext — inserts take pre-encrypted rows, select returns envelopes; the
  codec is bigint-safe. Removes the as-never/Record casts on the insert path.
- M1: type createEncryptionOperatorsV3 structurally ({ encrypt }) so the
  EncryptionV3() return value is accepted without a cast; add operators.test-d
  guarding it (the typecheck surface that catches the regression).
- Add bigint drizzle coverage (unit + live round-trip).
- B6: memoize per-column context so inArray builds once, not per element.
- C10: extract a shared drizzle:Name helper. C8: document the intentional
  v2/v3 EncryptionOperatorError fork. m3/m4: correct stale public.* comment and
  error text. TSDoc for the factory and ~20 operators.
- README: document @cipherstash/stack/eql/v3/drizzle.

Author: tobyhede

packages/stack/README.md

@@ -366,6 +366,87 @@ For columns with `searchableJson: true`, three JSONB operators are available:
 
 These operators encrypt the JSON path selector using the `steVecSelector` query type and cast it to `eql_v2_encrypted` for use with the EQL PostgreSQL functions.
 
+### EQL v3 Concrete-Type Columns (Drizzle)
+
+The `@cipherstash/stack/eql/v3/drizzle` module targets EQL v3, where each encrypted column is a **concrete Postgres domain type** (`eql_v3.text_eq`, `eql_v3.integer_ord`, …). Instead of toggling capability flags, you pick a concrete type from the `types` namespace and its query capabilities are fixed by that choice. The v2 `@cipherstash/stack/drizzle` module above is unchanged — this is an additive export.
+
+Declare a Drizzle table using the `types` factories. The suffix encodes the capability: `*Eq` (equality), `*Ord` (order + range, which also covers equality), `*Match` / `TextSearch` (free-text search), and the bare name (e.g. `Text`, `Bigint`) is storage-only.
+
+```ts
+import { pgTable, integer } from "drizzle-orm/pg-core"
+import { drizzle } from "drizzle-orm/postgres-js"
+import {
+  types,
+  createEncryptionOperatorsV3,
+  extractEncryptionSchemaV3,
+} from "@cipherstash/stack/eql/v3/drizzle"
+import { EncryptionV3 } from "@cipherstash/stack/v3"
+
+// Capabilities come from the concrete type — no flags to configure.
+const users = pgTable("users", {
+  id: integer("id").primaryKey().generatedAlwaysAsIdentity(),
+  email: types.TextEq("email"),      // equality: eq / ne / inArray
+  age: types.IntegerOrd("age"),      // order + range: gt/gte/lt/lte, between, asc/desc
+  bio: types.TextMatch("bio"),       // free-text search: contains
+  balance: types.Bigint("balance"),  // storage only (no query capability)
+})
+```
+
+Derive the v3 schema from the table, build the typed client, and create the capability-checked operators:
+
+```ts
+const usersSchema = extractEncryptionSchemaV3(users)
+const client = await EncryptionV3({ schemas: [usersSchema] })
+const ops = createEncryptionOperatorsV3(client)
+
+const db = drizzle({ client: sqlClient })
+```
+
+The operators auto-encrypt their operands and validate them against the column's concrete type. Applying an operator the type doesn't support throws `EncryptionOperatorError`:
+
+```ts
+// Equality — email is TextEq
+const exact = await db.select().from(users)
+  .where(await ops.eq(users.email, "alice@example.com"))
+
+// Range + ordering — age is IntegerOrd
+const adults = await db.select().from(users)
+  .where(await ops.gte(users.age, 18))
+  .orderBy(ops.asc(users.age))
+
+const midBand = await db.select().from(users)
+  .where(await ops.between(users.age, 25, 40))
+
+// Set membership — built on equality
+const listed = await db.select().from(users)
+  .where(await ops.inArray(users.email, ["alice@example.com", "bob@example.com"]))
+
+// Free-text token containment — bio is TextMatch
+const coffee = await db.select().from(users)
+  .where(await ops.contains(users.bio, "coffee"))
+```
+
+Rows are **pre-encrypted** with `client.bulkEncryptModels(...)` before they reach `db.insert(...).values(...)` — Drizzle never sees plaintext. `Bigint` columns take a native JS `bigint`:
+
+```ts
+const rows = await client.bulkEncryptModels(
+  [
+    { email: "alice@example.com", age: 30, bio: "climbing and coffee", balance: 100_000n },
+    { email: "bob@example.com", age: 41, bio: "cycling and coffee", balance: 250_000n },
+  ],
+  usersSchema,
+)
+if (rows.failure) throw new Error(rows.failure.message)
+
+await db.insert(users).values(rows.data)
+```
+
+Notes:
+
+- **Free-text search uses `ops.contains`** (token containment on a `match` index), not SQL `like` / `ilike`. It matches whole indexed tokens, so `contains(users.bio, "coffee")` finds rows whose `bio` contains the token `coffee`.
+- **The concrete type defines the legal operators.** `TextEq` supports `eq` / `ne` / `inArray` / `notInArray`; `*Ord` types add `gt` / `gte` / `lt` / `lte` / `between` / `notBetween` and `asc` / `desc`; `*Match` and `TextSearch` add `contains`; a bare `Text` / `Integer` / `Bigint` column is storage-only. Using an unsupported operator throws `EncryptionOperatorError`.
+- Combine conditions with `ops.and` / `ops.or`, and do NULL checks with `ops.isNull` / `ops.isNotNull` (the where-clause operators are `async` and must be `await`ed; `ops.asc` / `ops.desc` are synchronous).
+
 ## Identity-Aware Encryption
 
 Lock encryption to a specific user by requiring a valid JWT for decryption.
@@ -664,6 +745,8 @@ csValue(valueName)                 // returns ProtectValue (for nested values)
 | `@cipherstash/stack/secrets` | `Secrets` class and secrets types |
 | `@cipherstash/stack/client` | Client-safe exports (schema builders and types only - no native FFI) |
 | `@cipherstash/stack/types` | All TypeScript types (`Encrypted`, `Decrypted`, `ClientConfig`, `EncryptionClientConfig`, query types, etc.) |
+| `@cipherstash/stack/v3` | `EncryptionV3` typed client plus the EQL v3 authoring DSL (`encryptedTable`, `types`, v3 type helpers) |
+| `@cipherstash/stack/eql/v3/drizzle` | EQL v3 Drizzle integration: `types` column factories, `createEncryptionOperatorsV3`, `extractEncryptionSchemaV3`, `makeEqlV3Column`, `EncryptionOperatorError` |
 
 ## Migration from @cipherstash/protect
 

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

@@ -0,0 +1,99 @@
+import { type SQL, sql } from 'drizzle-orm'
+import { integer, PgDialect, pgTable } from 'drizzle-orm/pg-core'
+import { describe, expect, it, vi } from 'vitest'
+import { getEqlV3Column, isEqlV3Column } from '@/eql/v3/drizzle/column'
+import {
+  createEncryptionOperatorsV3,
+  EncryptionOperatorError,
+} from '@/eql/v3/drizzle/operators'
+import { types } from '@/eql/v3/drizzle/types'
+
+// A representative encrypted envelope — what `client.encrypt` actually returns
+// and what a bigint column stores. Deliberately NOT a plaintext bigint.
+const TERM = { c: 'ct', v: 1 }
+const TERM_JSON = JSON.stringify(TERM)
+
+function chainable(result: unknown) {
+  const op = result as {
+    withLockContext: ReturnType<typeof vi.fn>
+    audit: ReturnType<typeof vi.fn>
+  }
+  op.withLockContext = vi.fn(() => op)
+  op.audit = vi.fn(() => op)
+  return op
+}
+
+function setup() {
+  const encrypt = vi.fn(() => chainable(Promise.resolve({ data: TERM })))
+  const ops = createEncryptionOperatorsV3({ encrypt })
+  const dialect = new PgDialect()
+  const render = (s: SQL) => dialect.sqlToQuery(s)
+  return { ops, encrypt, render }
+}
+
+// A statically-typed table via the drizzle `types` namespace (no dynamic
+// matrix, no casts) — the column set is known at compile time.
+const accounts = pgTable('accounts', {
+  id: integer().primaryKey(),
+  balance: types.BigintOrd('balance'),
+  ledgerId: types.BigintEq('ledger_id'),
+  archived: types.Bigint('archived'),
+})
+
+describe('v3 drizzle bigint columns', () => {
+  it('detects a bigint column and reports its concrete public.bigint domain', () => {
+    const storage = types.Bigint('n')
+    const ord = types.BigintOrd('n_ord')
+
+    expect(isEqlV3Column(storage)).toBe(true)
+    expect(getEqlV3Column('n', storage)?.getEqlType()).toBe('public.bigint')
+    expect(getEqlV3Column('n_ord', ord)?.getEqlType()).toBe('public.bigint_ord')
+  })
+
+  it('emits the concrete public.bigint* SQL type through pgTable', () => {
+    expect(accounts.balance.getSQLType()).toBe('public.bigint_ord')
+    expect(accounts.ledgerId.getSQLType()).toBe('public.bigint_eq')
+    expect(accounts.archived.getSQLType()).toBe('public.bigint')
+  })
+
+  it('encrypts a native bigint operand for eq without JSON-stringifying it', async () => {
+    const { ops, encrypt, render } = setup()
+    // A value beyond Number.MAX_SAFE_INTEGER to prove the bigint is passed
+    // through untouched (a JSON.stringify of a bigint would have thrown).
+    const value = 9223372036854775807n
+    const q = render(await ops.eq(accounts.ledgerId, value))
+
+    expect(q.sql).toContain('eql_v3.eq("accounts"."ledger_id", $1::jsonb)')
+    expect(q.params).toEqual([TERM_JSON])
+    expect(encrypt.mock.calls[0]?.[0]).toBe(value)
+  })
+
+  it('emits ordering and range operators for a bigint_ord column', async () => {
+    const { ops, render } = setup()
+
+    const gt = render(await ops.gt(accounts.balance, 10n))
+    expect(gt.sql).toContain('eql_v3.gt("accounts"."balance", $1::jsonb)')
+
+    const between = render(await ops.between(accounts.balance, -5n, 5n))
+    expect(between.sql).toContain('eql_v3.gte("accounts"."balance", $1::jsonb)')
+    expect(between.sql).toContain('eql_v3.lte("accounts"."balance", $2::jsonb)')
+
+    const asc = render(ops.asc(accounts.balance))
+    expect(asc.sql).toContain('eql_v3.ord_term("accounts"."balance")')
+  })
+
+  it('rejects equality/ordering on a storage-only bigint column', async () => {
+    const { ops } = setup()
+    await expect(ops.eq(accounts.archived, 1n)).rejects.toBeInstanceOf(
+      EncryptionOperatorError,
+    )
+    expect(() => ops.asc(accounts.archived)).toThrow(EncryptionOperatorError)
+  })
+
+  it('rejects a bare SQL expression that is not an encrypted column', async () => {
+    const { ops } = setup()
+    await expect(ops.eq(sql`1`, 1n)).rejects.toBeInstanceOf(
+      EncryptionOperatorError,
+    )
+  })
+})

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

@@ -20,8 +20,12 @@ describe('v3 codec', () => {
     expect(v3FromDriver(obj)).toBe(obj)
   })
 
-  it('passes null/undefined through on read', () => {
+  it('normalises null/undefined to SQL NULL (JS null) on read', () => {
     expect(v3FromDriver(null)).toBeNull()
-    expect(v3FromDriver(undefined)).toBeUndefined()
+    expect(v3FromDriver(undefined)).toBeNull()
+  })
+
+  it('does not throw on a stray bigint in the envelope (defensive)', () => {
+    expect(v3ToDriver({ v: 1n } as never)).toBe('{"v":"1"}')
   })
 })

packages/stack/__tests__/drizzle-v3/operators-live-pg.test.ts

@@ -15,6 +15,7 @@ import {
   createEncryptionOperatorsV3,
   EncryptionOperatorError,
   extractEncryptionSchemaV3,
+  types as v3drizzle,
 } from '@/eql/v3/drizzle'
 import { makeEqlV3Column } from '@/eql/v3/drizzle/column'
 import { installEqlV3IfNeeded } from '../helpers/eql-v3'
@@ -54,7 +55,7 @@ const matrixTable = pgTable(TABLE_NAME, {
     V3_MATRIX['public.text_eq'].builder('nullable_text_eq'),
   ),
   ...matrixColumns,
-} as never)
+})
 
 const accountsTable = pgTable(ACCOUNT_TABLE_NAME, {
   id: integer('id').primaryKey().generatedAlwaysAsIdentity(),
@@ -63,12 +64,31 @@ const accountsTable = pgTable(ACCOUNT_TABLE_NAME, {
   testRunId: text('test_run_id').notNull(),
 })
 
+// A statically-typed encrypted table (via the drizzle `types` namespace) with
+// concrete bigint columns. Unlike the dynamic matrix table, its column set is
+// known at compile time, so it exercises A3 end-to-end with ZERO casts: the
+// insert takes envelope rows and the select yields `Encrypted` values ready for
+// decrypt.
+const BIGINT_TABLE_NAME = 'protect_ci_v3_drizzle_bigint'
+const bigintTable = pgTable(BIGINT_TABLE_NAME, {
+  id: integer('id').primaryKey().generatedAlwaysAsIdentity(),
+  rowKey: text('row_key').notNull(),
+  testRunId: text('test_run_id').notNull(),
+  balance: v3drizzle.BigintOrd('balance'),
+  ledger: v3drizzle.BigintEq('ledger'),
+})
+
+// Full i64 bounds — proves protect-ffi 0.28 round-trips a JS bigint beyond
+// Number.MAX_SAFE_INTEGER losslessly through the encrypted column.
+const BIGINT_BALANCE = 9223372036854775807n
+const BIGINT_LEDGER = -9223372036854775808n
+
 const schema = extractEncryptionSchemaV3(matrixTable)
+const bigintSchema = extractEncryptionSchemaV3(bigintTable)
 
 type PlainValue = string | number | boolean | Date
 type RowKey = typeof ROW_A | typeof ROW_B
 type MatrixPlainRow = Record<string, PlainValue | null | string>
-type MatrixDbRow = Record<string, unknown>
 type SelectRow = { rowKey: string }
 type Db = ReturnType<typeof drizzle>
 type Client = Awaited<ReturnType<typeof EncryptionV3>>
@@ -180,7 +200,7 @@ function encryptedInsertRows(): MatrixPlainRow[] {
 beforeAll(async () => {
   if (!LIVE_EQL_V3_PG_ENABLED) return
   await installEqlV3IfNeeded(sqlClient)
-  client = await EncryptionV3({ schemas: [schema] })
+  client = await EncryptionV3({ schemas: [schema, bigintSchema] })
   ops = createEncryptionOperatorsV3(client)
   db = drizzle({ client: sqlClient })
 
@@ -205,21 +225,42 @@ beforeAll(async () => {
       test_run_id TEXT NOT NULL
     )
   `)
+  await sqlClient.unsafe(`
+    CREATE TABLE IF NOT EXISTS ${BIGINT_TABLE_NAME} (
+      id INTEGER PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
+      row_key TEXT NOT NULL,
+      test_run_id TEXT NOT NULL,
+      balance public.bigint_ord NOT NULL,
+      ledger public.bigint_eq NOT NULL
+    )
+  `)
 
-  const encryptedRows = unwrap<MatrixDbRow[]>(
+  const encryptedRows = unwrap(
     await client.bulkEncryptModels(encryptedInsertRows(), schema),
   )
   await db.insert(matrixTable).values(encryptedRows)
   await db.insert(accountsTable).values([
     { rowKey: ROW_A, label: 'primary', testRunId: RUN },
     { rowKey: ROW_B, label: 'secondary', testRunId: RUN },
   ])
+
+  // A3 end-to-end, cast-free: encrypt a native bigint model, insert the
+  // resulting envelope rows (typed against the column's `Encrypted` data slot),
+  // no `as never` anywhere.
+  const bigintRows = unwrap(
+    await client.bulkEncryptModels(
+      [{ rowKey: ROW_A, testRunId: RUN, balance: BIGINT_BALANCE, ledger: BIGINT_LEDGER }],
+      bigintSchema,
+    ),
+  )
+  await db.insert(bigintTable).values(bigintRows)
 }, 120000)
 
 afterAll(async () => {
   if (!LIVE_EQL_V3_PG_ENABLED) return
   await sqlClient`DELETE FROM ${sqlClient(TABLE_NAME)} WHERE test_run_id = ${RUN}`
   await sqlClient`DELETE FROM ${sqlClient(ACCOUNT_TABLE_NAME)} WHERE test_run_id = ${RUN}`
+  await sqlClient`DELETE FROM ${sqlClient(BIGINT_TABLE_NAME)} WHERE test_run_id = ${RUN}`
   await sqlClient.end()
 }, 30000)
 
@@ -556,4 +597,45 @@ describeLivePg('v3 drizzle operators (live pg matrix)', () => {
     // Only '' is excluded (ROW_A); ROW_B ('ada@example.com') survives.
     expect(rows).toEqual([ROW_B])
   }, 30000)
+
+  // A3 + bigint lock: a statically-typed bigint table round-trips a real i64
+  // value through encrypt → insert → select → decrypt with no casts. The select
+  // yields `Encrypted`-typed columns (the envelope), fed straight to decrypt.
+  it('round-trips a native bigint through a statically-typed encrypted column', async () => {
+    const encrypted = await db
+      .select({ balance: bigintTable.balance, ledger: bigintTable.ledger })
+      .from(bigintTable)
+      .where(drizzleEq(bigintTable.testRunId, RUN))
+    expect(encrypted).toHaveLength(1)
+
+    const decrypted = unwrap(
+      await client.decryptModel(encrypted[0], bigintSchema),
+    )
+    expect(decrypted.balance).toBe(BIGINT_BALANCE)
+    expect(decrypted.ledger).toBe(BIGINT_LEDGER)
+  }, 30000)
+
+  it('filters a bigint column by encrypted equality and ordering', async () => {
+    const byLedger = (await db
+      .select({ rowKey: bigintTable.rowKey })
+      .from(bigintTable)
+      .where(
+        and(
+          drizzleEq(bigintTable.testRunId, RUN),
+          await ops.eq(bigintTable.ledger, BIGINT_LEDGER),
+        ),
+      )) as SelectRow[]
+    expect(byLedger.map((row) => row.rowKey)).toEqual([ROW_A])
+
+    const byBalance = (await db
+      .select({ rowKey: bigintTable.rowKey })
+      .from(bigintTable)
+      .where(
+        and(
+          drizzleEq(bigintTable.testRunId, RUN),
+          await ops.gt(bigintTable.balance, 0n),
+        ),
+      )) as SelectRow[]
+    expect(byBalance.map((row) => row.rowKey)).toEqual([ROW_A])
+  }, 30000)
 })

packages/stack/__tests__/drizzle-v3/operators.test-d.ts

@@ -0,0 +1,37 @@
+import { describe, expectTypeOf, it } from 'vitest'
+import type { EncryptionClient } from '@/encryption'
+import type { EncryptionV3 } from '@/encryption/v3'
+import { createEncryptionOperatorsV3 } from '@/eql/v3/drizzle'
+
+/**
+ * Static regression guard for M1: `createEncryptionOperatorsV3` must accept the
+ * `TypedEncryptionClient` that `EncryptionV3` resolves to — the documented
+ * `createEncryptionOperatorsV3(await EncryptionV3({ schemas }))` usage — as well
+ * as the nominal `EncryptionClient` and a hand-rolled `{ encrypt }` double,
+ * none requiring a cast. Typing the parameter to `EncryptionClient` (the
+ * original bug) makes the first call below a compile error, which this suite
+ * would then catch. Lives in a `*.test-d.ts` so it is inside the existing
+ * typecheck scope without dragging the loose-typed runtime suites in.
+ */
+describe('createEncryptionOperatorsV3 - client parameter (M1)', () => {
+  type V3Client = Awaited<ReturnType<typeof EncryptionV3>>
+
+  it('accepts the client EncryptionV3 returns with no cast', () => {
+    expectTypeOf(createEncryptionOperatorsV3).toBeCallableWith(
+      {} as V3Client,
+    )
+  })
+
+  it('still accepts the nominal EncryptionClient', () => {
+    expectTypeOf(createEncryptionOperatorsV3).toBeCallableWith(
+      {} as EncryptionClient,
+    )
+  })
+
+  it('accepts a minimal structural { encrypt } double', () => {
+    const double = {
+      encrypt: (_plaintext: never, _opts: never) => ({}) as unknown,
+    }
+    expectTypeOf(createEncryptionOperatorsV3).toBeCallableWith(double)
+  })
+})