feat(prisma-next): v3 query operators — eql_v3.* lowering + capability gating

Add cipherstashV3QueryOperations() (src/v3/operators-v3.ts): the EQL v3
operator set registered by the v3 extension descriptor only (decision 1b
— same cipherstash* method names as v2, never co-registered; the flat
OperationRegistry collision is pinned by test).

Lowering matches the stack-drizzle v3 dialect byte-for-byte: operands
are ciphertext-free query terms cast to the column domain's
eql_v3.query_<domain> type (eql_v3.eq/neq/gt/gte/lt/lte/contains,
self-parenthesised (gte AND lte) range, OR-of-eq membership), JSON
containment is OPERATOR(public.@>) with the irregular
::eql_v3.query_jsonb cast (cipherstashJsonContains, empty-needle
guarded), and ordering extracts eql_v3.ord_term / ord_term_ore by the
domain's flavour via the free-standing cipherstashV3Asc/Desc helpers.

Operands are bound as pg/text@1 params (bare $N; the template supplies
the query cast — the column codec's storage-domain cast would fail the
query term's CHECK) and each envelope is routing-key stamped plus
marked with its queryType (markV3QueryTerm / v3QueryTermTypeOf), the
seam Task 7's SDK adapter uses to route WHERE operands through
encryptQuery instead of storage bulkEncrypt.

Every operator gates on the concrete domain's catalog capabilities and
throws the v3-owned EncryptionOperatorError naming column, domain,
operator, and missing capability. v3 codec descriptors are pinned to
cipherstash:*-only traits alongside the v2 equality-trait regression.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: calvinbrewer

packages/prisma-next/src/v3/operators-v3.ts

@@ -36,6 +36,7 @@ import { createCipherstashStringCodec } from '../src/execution/codec-runtime'
 import { createParameterizedCodecDescriptors } from '../src/execution/parameterized'
 import type { CipherstashSdk } from '../src/execution/sdk'
 import { cipherstashStringCodecMetadata } from '../src/extension-metadata/codec-metadata'
+import { createV3CodecDescriptors } from '../src/v3/codec-runtime-v3'
 
 function emptySdk(): CipherstashSdk {
   return {
@@ -90,6 +91,26 @@ describe('cipherstash codec: no `equality` trait', () => {
   })
 })
 
+describe('cipherstash v3 codec descriptors: no framework built-in traits', () => {
+  it('every v3 descriptor advertises only cipherstash:* traits — never the framework built-in `equality`', () => {
+    // Same footgun as v2, per-domain: a framework built-in trait on a
+    // v3 codec descriptor would re-attach the built-in `eq` (SQL `=`)
+    // to encrypted columns, which silently returns zero rows against
+    // nondeterministic ciphertexts. Storage-only domains legitimately
+    // carry an EMPTY trait list (they answer no operator at all), so
+    // the invariant is subset-of-`cipherstash:*`, not non-empty.
+    const descriptors = createV3CodecDescriptors(emptySdk())
+    expect(descriptors.length).toBeGreaterThan(0)
+    for (const descriptor of descriptors) {
+      const traits: ReadonlyArray<string> = descriptor.traits ?? []
+      for (const trait of traits) {
+        expect(String(trait).startsWith('cipherstash:')).toBe(true)
+      }
+      expect(traits).not.toContain('equality')
+    }
+  })
+})
+
 describe('cipherstash columns: framework built-in `eq` is not reachable', () => {
   it('documents the gating contract — built-in `eq` requires `equality` in column traits', () => {
     // This test pins the contract that `cipherstash/string@1` columns

packages/prisma-next/test/equality-trait-removal.test.ts

@@ -0,0 +1,193 @@
+/**
+ * v3 operator capability gating + registration constraints.
+ *
+ * Every v3 operator gates on the CONCRETE domain's query capabilities
+ * (derived from the catalog by codec id) before building any AST, and
+ * throws `EncryptionOperatorError` naming the column, domain, operator,
+ * and missing capability. Trait dispatch alone is not enough: traits
+ * are per-codec, and a caller reaching the operator descriptor directly
+ * (or through a custom builder) must still be stopped when the domain
+ * cannot answer the operator.
+ *
+ * Also pins decision 1b's registration constraint: the v3 descriptor
+ * stands alone (a v3-only adapter builds cleanly), and co-registering
+ * the v2 and v3 descriptors throws — the framework's flat
+ * `OperationRegistry` rejects two descriptors sharing the
+ * `cipherstashEq` method name. v2 and v3 are separate entry points,
+ * never composed into one client.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { createCipherstashRuntimeDescriptor } from '../../src/exports/runtime'
+import {
+  cipherstashV3Asc,
+  cipherstashV3QueryOperations,
+  EncryptionOperatorError,
+} from '../../src/v3/operators-v3'
+import {
+  assembleV3ExecutionContext,
+  BOOLEAN_CODEC_ID,
+  callOperator,
+  columnAccessorV3,
+  emptySdk,
+  getOperator,
+  JSON_CODEC_ID,
+  makeV3Adapter,
+  TABLE,
+  TEXT_EQ_CODEC_ID,
+  TEXT_STORAGE_CODEC_ID,
+  v3RuntimeDescriptor,
+} from './operator-lowering-v3.helpers'
+
+describe('v3 operator capability gating', () => {
+  it('equality requires the equality capability — storage-only eql_v3_text rejects cipherstashEq', () => {
+    expect(() =>
+      callOperator(
+        getOperator('cipherstashEq'),
+        columnAccessorV3(TABLE, 'note', TEXT_STORAGE_CODEC_ID),
+        'x',
+      ),
+    ).toThrow(EncryptionOperatorError)
+  })
+
+  it('names the column, domain, operator, and missing capability in the diagnostic', () => {
+    try {
+      callOperator(
+        getOperator('cipherstashEq'),
+        columnAccessorV3(TABLE, 'note', TEXT_STORAGE_CODEC_ID),
+        'x',
+      )
+      expect.unreachable('cipherstashEq on a storage-only column must throw')
+    } catch (error) {
+      expect(error).toBeInstanceOf(EncryptionOperatorError)
+      const operatorError = error as EncryptionOperatorError
+      expect(operatorError.message).toContain('cipherstashEq')
+      expect(operatorError.message).toContain('equality')
+      expect(operatorError.message).toContain('"note"')
+      expect(operatorError.message).toContain('public.eql_v3_text')
+      expect(operatorError.context).toEqual({
+        columnName: 'note',
+        tableName: TABLE,
+        operator: 'cipherstashEq',
+      })
+    }
+  })
+
+  it('comparison requires order/range — text_eq rejects cipherstashGt', () => {
+    expect(() =>
+      callOperator(
+        getOperator('cipherstashGt'),
+        columnAccessorV3(TABLE, 'nickname', TEXT_EQ_CODEC_ID),
+        'x',
+      ),
+    ).toThrow(/order\/range/)
+  })
+
+  it('free-text requires the match index — text_eq rejects cipherstashIlike', () => {
+    expect(() =>
+      callOperator(
+        getOperator('cipherstashIlike'),
+        columnAccessorV3(TABLE, 'nickname', TEXT_EQ_CODEC_ID),
+        'x',
+      ),
+    ).toThrow(/free-text/)
+  })
+
+  it('JSON containment requires searchableJson — text_eq rejects cipherstashJsonContains', () => {
+    expect(() =>
+      callOperator(
+        getOperator('cipherstashJsonContains'),
+        columnAccessorV3(TABLE, 'nickname', TEXT_EQ_CODEC_ID),
+        { role: 'admin' },
+      ),
+    ).toThrow(/JSON containment/)
+  })
+
+  it('eql_v3_json is searchableJson-only — rejects cipherstashEq', () => {
+    expect(() =>
+      callOperator(
+        getOperator('cipherstashEq'),
+        columnAccessorV3(TABLE, 'payload', JSON_CODEC_ID),
+        { role: 'admin' },
+      ),
+    ).toThrow(/equality/)
+  })
+
+  it('storage-only eql_v3_boolean rejects every search operator', () => {
+    for (const method of [
+      'cipherstashEq',
+      'cipherstashNe',
+      'cipherstashGt',
+      'cipherstashIlike',
+      'cipherstashJsonContains',
+    ]) {
+      expect(() =>
+        callOperator(
+          getOperator(method),
+          columnAccessorV3(TABLE, 'active', BOOLEAN_CODEC_ID),
+          true,
+        ),
+      ).toThrow(EncryptionOperatorError)
+    }
+  })
+
+  it('ordering helpers gate on order/range — text_eq rejects cipherstashV3Asc', () => {
+    expect(() =>
+      cipherstashV3Asc(columnAccessorV3(TABLE, 'nickname', TEXT_EQ_CODEC_ID)),
+    ).toThrow(/order\/range/)
+  })
+
+  it('rejects a non-v3 codec id (v2 columns are the wrong entry point)', () => {
+    expect(() =>
+      callOperator(
+        getOperator('cipherstashEq'),
+        columnAccessorV3(TABLE, 'email', 'cipherstash/string@1'),
+        'x',
+      ),
+    ).toThrow(/not a .*v3 domain/)
+  })
+
+  it('rejects a self expression with no codec binding', () => {
+    expect(() =>
+      callOperator(
+        getOperator('cipherstashEq'),
+        {
+          buildAst: () => {
+            throw new Error('unreachable')
+          },
+        },
+        'x',
+      ),
+    ).toThrow(/missing a CodecRef/)
+  })
+})
+
+describe('v3 descriptor registration (decision 1b)', () => {
+  it('a v3-only adapter builds and registers its operation set cleanly', () => {
+    expect(() => makeV3Adapter()).not.toThrow()
+    // The execution context is what assembles the flat operation
+    // registry from `queryOperations()` — a v3-only stack registers the
+    // full `cipherstash*` method set without collision.
+    const registered = Object.keys(
+      assembleV3ExecutionContext().queryOperations.entries(),
+    )
+    expect(registered).toEqual(
+      expect.arrayContaining([...Object.keys(cipherstashV3QueryOperations())]),
+    )
+  })
+
+  it('co-registering the v2 and v3 descriptors throws on the shared method names', () => {
+    // Both descriptors define `cipherstashEq` (and eleven siblings); the
+    // flat, method-keyed OperationRegistry disallows override. This is
+    // WHY v2 and v3 are separate entry points that are never composed
+    // into one client. The registry is assembled when the execution
+    // context is built against a contract, so the collision surfaces
+    // there rather than at adapter construction.
+    expect(() =>
+      assembleV3ExecutionContext([
+        createCipherstashRuntimeDescriptor({ sdk: emptySdk() }),
+        v3RuntimeDescriptor(),
+      ]),
+    ).toThrow(/already registered/)
+  })
+})