refactor(prisma-next): apply multi-agent review fixes (v3)

- Remove dead v3Dialect.orderBy() (unreachable — cipherstashAsc/Desc are v2-only);
  document that v3 ORDER BY sort is not yet wired (README + e2e header).
- Fix stale eqlOperator docblock (now trait-dispatched + dialect-selected, not
  pinned to string@1 / eql_v2).
- Reuse FLAG_DISPATCH in applyV3Index instead of a parallel if-chain.
- Expand tests: full index/operator mismatch matrix, V3_ENVELOPE_COERCERS reject
  path, setHandleQueryType write-once-wins conflict, encryptQuery failure branch;
  tighten the sdk-adapter column assertion; add gt/lte e2e ord cases.
- Align vendor-script + migration regen comments with the actual invocation.

Author: tobyhede

examples/prisma/test/e2e/helpers/eql-v3-seed.ts

@@ -33,6 +33,3 @@ export const oracleBetween = (lo: string, hi: string) =>
   ids(v3Seed.filter((r) => r.label >= lo && r.label <= hi))
 export const oracleInArray = (targets: ReadonlyArray<string>) =>
   ids(v3Seed.filter((r) => targets.includes(r.label)))
-
-// Ascending labels (text_ord) — for the order-by assertion.
-export const oracleAscLabels = () => [...v3Seed].map((r) => r.label).sort((a, b) => a.localeCompare(b))

examples/prisma/test/e2e/str-v3.e2e.test.ts

@@ -6,7 +6,10 @@
  * index columns:
  *   - email (text_eq)    — cipherstashEq / Ne / InArray / NotInArray
  *   - bio   (text_match) — cipherstashIlike / NotIlike (containment)
- *   - name  (text_ord)   — cipherstashLt/Lte/Gt/Gte/Between + asc/desc order
+ *   - name  (text_ord)   — cipherstashLt / Lte / Gt / Between (ORE comparison)
+ *
+ * (Ordered `ORDER BY` sort is not yet wired for v3 — see the package README — so
+ * this matrix covers the range/comparison predicates only.)
  *
  * Gated on DATABASE_URL (set by global-setup once the harness Postgres + ZeroKMS
  * credentials are configured); skips cleanly otherwise.
@@ -18,8 +21,10 @@ import {
   oracleBetween,
   oracleContains,
   oracleEq,
+  oracleGt,
   oracleInArray,
   oracleLt,
+  oracleLte,
   oracleNe,
   v3Seed,
 } from './helpers/eql-v3-seed'
@@ -69,9 +74,13 @@ describe.skipIf(!dbUrl)('EQL v3 String e2e (live PG + eql_v3 + ZeroKMS)', () =>
     )
   })
 
-  it('lt / between on text_ord match the ord oracle', async () => {
+  it('lt / lte / gt / between on text_ord match the ORE comparison oracles', async () => {
     const lt = await db.orm.UserV3.where((u) => u.name.cipherstashLt('banana')).all()
     expect(lt.map((r) => r.id).sort()).toEqual(oracleLt('banana'))
+    const lte = await db.orm.UserV3.where((u) => u.name.cipherstashLte('banana')).all()
+    expect(lte.map((r) => r.id).sort()).toEqual(oracleLte('banana'))
+    const gt = await db.orm.UserV3.where((u) => u.name.cipherstashGt('banana')).all()
+    expect(gt.map((r) => r.id).sort()).toEqual(oracleGt('banana'))
     const between = await db.orm.UserV3.where((u) => u.name.cipherstashBetween('aardvark', 'cherry')).all()
     expect(between.map((r) => r.id).sort()).toEqual(oracleBetween('aardvark', 'cherry'))
   })

packages/prisma-next/README.md

@@ -125,7 +125,7 @@ model Doc {
 | `orderAndRange`   | `eql_v3.text_ord`  | `cipherstashGt` / `cipherstashGte` / `cipherstashLt` / `cipherstashLte` / `cipherstashBetween` / `cipherstashNotBetween` |
 | `freeTextSearch`  | `eql_v3.text_match`| `cipherstashIlike` / `cipherstashNotIlike` (containment)                            |
 
-Applying an operator that needs a different index than the column declares (e.g. `cipherstashGt` on an `equality` column) is rejected with a clear `TypeError` at **query-build time** — a runtime guard, not compile-time gating (milestone-1 trade-off; per-index codec ids could restore compile-time gating later). The v3 baseline migration installs the `eql_v3` bundle alongside the v2 bundle; both `bulkEncryptMiddleware` and `bulkEncryptV3Middleware` register over the same SDK and ignore each other's columns.
+Ordered `ORDER BY` sort (`cipherstashAsc` / `cipherstashDesc`) is **not yet wired for v3** — those helpers currently accept v2 columns only. Applying an operator that needs a different index than the column declares (e.g. `cipherstashGt` on an `equality` column) is rejected with a clear `TypeError` at **query-build time** — a runtime guard, not compile-time gating (milestone-1 trade-off; per-index codec ids could restore compile-time gating later). The v3 baseline migration installs the `eql_v3` bundle alongside the v2 bundle; both `bulkEncryptMiddleware` and `bulkEncryptV3Middleware` register over the same SDK and ignore each other's columns.
 
 ## Authentication
 

packages/prisma-next/migrations/20260601T0100_install_eql_v3_bundle/migration.ts

@@ -12,7 +12,8 @@
  * (applied via the codec hook's `expandNativeType`) encodes the index capability.
  *
  * Authoring loop: hand-edited; re-emit `ops.json` / `migration.json` after edits
- * via `node migration.ts`.
+ * by running this file through a TypeScript loader (the imports below are
+ * extensionless TS) — e.g. `pnpm dlx tsx migration.ts`.
  */
 import { Migration, MigrationCLI, rawSql } from '@prisma-next/target-postgres/migration';
 import { CIPHERSTASH_INVARIANTS } from '../../src/extension-metadata/constants';

packages/prisma-next/scripts/vendor-eql-v3-install.ts

@@ -27,7 +27,8 @@ writeFileSync(
     `//\n` +
     `// This file is committed to source control so dev environments and offline\n` +
     `// builds work without network access. Regenerate with\n` +
-    `// \`pnpm tsx scripts/vendor-eql-v3-install.ts\` after refreshing the fixture.\n` +
+    `// \`node --experimental-strip-types scripts/vendor-eql-v3-install.ts\` after\n` +
+    `// refreshing the fixture (see scripts/REFRESH_EQL_V3.md).\n` +
     `export const EQL_V3_INSTALL_VERSION = '${VERSION}' as const\n` +
     `export const EQL_V3_INSTALL_SQL: string = \`${escaped}\`\n`,
 )

packages/prisma-next/src/execution/codec-runtime.ts

@@ -2,14 +2,18 @@
  * Cipherstash storage codec runtimes — wrap each `Encrypted*` envelope
  * at the SQL codec boundary.
  *
- * Every cipherstash codec has identical encode/decode bodies (the
- * `eql_v2_encrypted` composite-literal wire format is determined by
- * the EQL type definition, not by the plaintext type). The shared body
- * lives in `./cell-codec-factory.ts`; the per-codec wrappers below
- * supply only the per-type discriminators (codec id, user-facing type
- * name, envelope `fromInternal` factory) and re-export the codec class
- * for backwards compatibility with consumers that imported it directly
- * from this module.
+ * The six v2 cipherstash codecs share identical encode/decode bodies
+ * (the `eql_v2_encrypted` composite-literal wire format is determined
+ * by the EQL type definition, not by the plaintext type). The v3 string
+ * codec (re-exported below from `./codec-v3.ts`) reuses the same shared
+ * body but OVERRIDES `encodeWire`/`decodeWire` for the plain-jsonb v3
+ * domain wire (`eql_v3.text*` columns are `CREATE DOMAIN … AS jsonb`,
+ * not the v2 composite literal). The shared body lives in
+ * `./cell-codec-factory.ts`; the per-codec wrappers below supply only
+ * the per-type discriminators (codec id, user-facing type name, envelope
+ * `fromInternal` factory) and re-export the codec class for backwards
+ * compatibility with consumers that imported it directly from this
+ * module.
  *
  * Mirrors the `makeCipherstashCodecHooks` pattern on the migration
  * plane (see `../migration/codec-hooks-factory.ts`) — same shape,

packages/prisma-next/src/execution/dialect.ts

@@ -15,15 +15,13 @@ export interface SqlDialect {
   comparison(op: ComparisonOp): string
   range(): string
   match(op: MatchOp): string
-  orderBy(): string
 }
 
 export const v2Dialect: SqlDialect = {
   equality: (op) => (op === 'eq' ? 'eql_v2.eq({{self}}, {{arg0}})' : 'NOT eql_v2.eq({{self}}, {{arg0}})'),
   comparison: (op) => `eql_v2.${op}({{self}}, {{arg0}})`,
   range: () => 'eql_v2.gte({{self}}, {{arg0}}) AND eql_v2.lte({{self}}, {{arg1}})',
   match: (op) => `eql_v2.${op === 'like' ? 'ilike' : op}({{self}}, {{arg0}})`,
-  orderBy: () => 'eql_v2.order_by({{self}})',
 }
 
 const ORD_SYMBOL: Record<ComparisonOp, string> = { gt: '>', gte: '>=', lt: '<', lte: '<=' }
@@ -47,7 +45,6 @@ export const v3Dialect: SqlDialect = {
     'eql_v3.ord_term({{self}}) >= eql_v3.ore_block_u64_8_256({{arg0}}::jsonb) AND ' +
     'eql_v3.ord_term({{self}}) <= eql_v3.ore_block_u64_8_256({{arg1}}::jsonb)',
   match: () => 'eql_v3.match_term({{self}}) @> eql_v3.bloom_filter({{arg0}}::jsonb)',
-  orderBy: () => 'eql_v3.ord_term({{self}})',
 }
 
 // Route by codec id: a column's wire/operator family is fixed by its codec id,

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

@@ -323,16 +323,18 @@ function extractColumnRef(selfAst: AnyExpression): ColumnRef | undefined {
 }
 
 /**
- * Build a single-codec cipherstash operator descriptor — the
- * original shape used by `cipherstashEq` / `cipherstashIlike`,
- * pinned to `cipherstash/string@1`. Multi-codec operators use
- * {@link envelopeOperator} with trait-based dispatch instead.
+ * Build the single-ARG cipherstash operator descriptor used by
+ * `cipherstashEq` / `cipherstashIlike`. Dispatches on the shared
+ * `cipherstash:string` trait (carried by BOTH `cipherstash/string@1` and
+ * `cipherstash/string-v3@1`, and only those), so it attaches to v2 AND v3 string
+ * columns; the v2/v3 SQL split is chosen at `impl` time via
+ * {@link dialectForCodecId}. Multi-codec operators use {@link envelopeOperator}.
  *
- * @param publicMethod - The user-facing method name on the column
- *   accessor (e.g. `cipherstashEq`). Must not collide with any
- *   framework- or adapter-shipped method name.
- * @param eqlFunction - The EQL function to lower to (`eq`, `ilike`).
- *   Embedded into the SQL lowering template as `eql_v2.<eqlFunction>(...)`.
+ * @param publicMethod - The user-facing method name on the column accessor (e.g.
+ *   `cipherstashEq`). Must not collide with any framework- or adapter-shipped name.
+ * @param eqlFunction - Selects the dialect template (`equality('eq')` for `eq`,
+ *   `match('like')` for `ilike`), lowered to `eql_v2.*` or `eql_v3.*` per the
+ *   column's codec. Also selects the v3 `queryType` for the index/operator guard.
  */
 function eqlOperator(publicMethod: string, eqlFunction: 'eq' | 'ilike'): SqlOperationDescriptor {
   // `eq` carries an equality index; `ilike` (free-text containment) carries the

packages/prisma-next/src/execution/parameterized.ts

@@ -10,23 +10,26 @@
  * so each `createParameterizedCodecDescriptors(sdk)` call produces a
  * fresh descriptor list closed over the SDK so multi-tenant
  * deployments can compose multiple cipherstash extensions side-by-side
- * without cross-talk; and the cipherstash family ships six codecs
- * (one per encrypted column type) which all share the same
- * `eql_v2_encrypted` Postgres native type.
+ * without cross-talk; and the cipherstash family ships SEVEN codecs.
+ * The six v2 codecs (one per encrypted column type) all share the same
+ * `eql_v2_encrypted` Postgres native type; the seventh — the EQL v3
+ * string codec — uses its OWN `jsonb` param-cast type backed by the
+ * per-column `eql_v3.text*` domains (NOT `eql_v2_encrypted`).
  *
  * Per-codec params shape (every flag defaults to `true` because
  * searchable encryption is the legitimate default for an extension
  * whose entire reason for existing is to make encrypted columns
  * queryable):
  *
- * | Codec               | Params                              |
- * |---------------------|-------------------------------------|
- * | `cipherstash/string@1`  | `{ equality, freeTextSearch, orderAndRange }` |
- * | `cipherstash/double@1`  | `{ equality, orderAndRange }`   |
- * | `cipherstash/bigint@1`  | `{ equality, orderAndRange }`   |
- * | `cipherstash/date@1`    | `{ equality, orderAndRange }`   |
- * | `cipherstash/boolean@1` | `{ equality }`                  |
- * | `cipherstash/json@1`    | `{ searchableJson }`            |
+ * | Codec                      | Params                              |
+ * |----------------------------|-------------------------------------|
+ * | `cipherstash/string@1`     | `{ equality, freeTextSearch, orderAndRange }` |
+ * | `cipherstash/double@1`     | `{ equality, orderAndRange }`   |
+ * | `cipherstash/bigint@1`     | `{ equality, orderAndRange }`   |
+ * | `cipherstash/date@1`       | `{ equality, orderAndRange }`   |
+ * | `cipherstash/boolean@1`    | `{ equality }`                  |
+ * | `cipherstash/json@1`       | `{ searchableJson }`            |
+ * | `cipherstash/string-v3@1`  | `{ index }` (single v3 index choice; native type `jsonb`/`eql_v3.text*`, NOT `eql_v2_encrypted`) |
  *
  * The codec runtimes are per-cell stateless across params on the write
  * side (encode reads ciphertext from the handle, independent of the

packages/prisma-next/src/execution/sdk.ts

@@ -83,7 +83,7 @@ export interface CipherstashBulkEncryptQueryArgs {
  * implement these three methods directly.
  */
 export interface CipherstashSdk {
-  decrypt(args: CipherstashSingleDecryptArgs): Promise<string>;
+  decrypt(args: CipherstashSingleDecryptArgs): Promise<unknown>;
   bulkEncrypt(args: CipherstashBulkEncryptArgs): Promise<ReadonlyArray<unknown>>;
   bulkDecrypt(args: CipherstashBulkDecryptArgs): Promise<ReadonlyArray<unknown>>;
   /**