fix(prisma-next): PR #655 review hardening across the v3 seams

- wire-v3: v3ToDriver coerces JSON.stringify's undefined branch to null;
  v3FromDriver gains overloads so a nullable input yields a nullable
  result instead of laundering null into T.
- sdk-adapter-v3: bulkDecrypt validates response cardinality (a
  truncated response would silently misalign plaintexts); the
  deliberate as-never bridges carry the repo's biome suppression.
- pack meta: extensionPacks.cipherstash now registers the 40 v3 codec
  metadata instances + storage rows (derived from the catalog, never
  hand-listed) and the EncryptedNumber type import, so consumer
  contracts describe the codecs their fields use.
- live suites: direct dotenv/config imports, canonical column-order
  binding in insertEncryptedRows (a differing key order could bind
  values to the wrong SQL columns), and migration-apply now uninstalls
  EQL v3 first so the customer-facing migration SQL genuinely executes
  on a reused database (test:live is serial now — the reinstall is
  destructive across files).
- bundling-isolation: entry checks scan the complete import graph for
  every v2 wire/codec-factory marker, not just entry bodies.

Verified live: 599 unit + 30 live-PG + 582 integration + 40 example-e2e
+ 7 README-walkthrough tests green against real ZeroKMS + Postgres.

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

Author: calvinbrewer

packages/prisma-next/package.json

@@ -77,7 +77,8 @@
 		"dev": "tsup --watch",
 		"test": "vitest run",
 		"test:coverage": "vitest run --coverage",
-		"test:live": "vitest run test/live",
+		"test:live": "vitest run test/live --fileParallelism=false",
+		"test:integration": "vitest run --config integration/vitest.config.ts",
 		"typecheck": "tsc --project tsconfig.json --noEmit",
 		"lint": "biome check . --error-on-warnings",
 		"lint:fix": "biome check --write .",
@@ -99,6 +100,7 @@
 	},
 	"devDependencies": {
 		"@cipherstash/eql": "3.0.0",
+		"@cipherstash/test-kit": "workspace:*",
 		"@prisma-next/adapter-postgres": "0.14.0",
 		"@prisma-next/cli": "0.14.0",
 		"@prisma-next/driver-postgres": "0.14.0",
@@ -108,6 +110,7 @@
 		"@prisma-next/sql-contract-ts": "0.14.0",
 		"@prisma-next/sql-schema-ir": "0.14.0",
 		"@prisma-next/target-postgres": "0.14.0",
+		"dotenv": "17.4.2",
 		"fast-check": "^4.8.0",
 		"pathe": "^2.0.3",
 		"postgres": "^3.4.8",

packages/prisma-next/src/extension-metadata/codec-metadata.ts

@@ -26,7 +26,13 @@ import type { JsonValue } from '@prisma-next/contract/types'
 import {
   type AnyCodecDescriptor,
   CodecImpl,
+  type CodecTrait,
 } from '@prisma-next/framework-components/codec'
+import {
+  envelopeTypeNameForCastAs,
+  V3_DOMAIN_META_BY_CODEC_ID,
+  type V3DomainMeta,
+} from '../v3/catalog'
 import {
   CIPHERSTASH_BIGINT_CODEC_ID,
   CIPHERSTASH_BOOLEAN_CODEC_ID,
@@ -37,6 +43,7 @@ import {
   CIPHERSTASH_STRING_CODEC_ID,
   EQL_V2_ENCRYPTED_TYPE,
 } from './constants'
+import { v3TraitsForCapabilities } from './constants-v3'
 
 function makeMetadataDescriptor(
   codecId: string,
@@ -132,3 +139,68 @@ export const cipherstashJsonCodecMetadata = new CipherstashCodecMetadata(
   makeMetadataDescriptor(CIPHERSTASH_JSON_CODEC_ID, 'EncryptedJson'),
   'EncryptedJson',
 )
+
+// ---------------------------------------------------------------------------
+// EQL v3 — one metadata codec per catalog domain (all 40), DERIVED from the
+// catalog (never hand-listed) so pack-meta can never drift from what the
+// runtime registers. Mirrors the truthful metadata of the runtime auxiliary
+// descriptors in `../v3/codec-runtime-v3.ts` (traits from capabilities,
+// concrete `public.eql_v3_*` native type, `isParameterized: true` for the
+// static `{ castAs, capabilities }` typeParams block v3 authoring emits) —
+// minus the SDK-bound encode/decode, which pack-meta consumers never call.
+// The catalog import stays SDK/envelope-free, preserving the control-vs-
+// runtime bundling split this module's header describes.
+// ---------------------------------------------------------------------------
+
+function makeV3MetadataDescriptor(
+  codecId: string,
+  meta: V3DomainMeta,
+  typeName: string,
+): AnyCodecDescriptor {
+  return {
+    codecId,
+    // Type-level adapter into the framework's closed `CodecTrait` union —
+    // same rationale as `v3CodecTraits` in `../v3/codec-runtime-v3.ts`.
+    traits: v3TraitsForCapabilities(meta.capabilities) as readonly CodecTrait[],
+    targetTypes: [meta.nativeType],
+    meta: { db: { sql: { postgres: { nativeType: meta.nativeType } } } },
+    paramsSchema: {
+      '~standard': {
+        version: 1,
+        vendor: 'cipherstash',
+        validate: (value: unknown) => ({ value }),
+      },
+    },
+    isParameterized: true,
+    renderOutputType: () => typeName,
+    factory: () => () => {
+      throw new Error(
+        'cipherstash codec: metadata descriptor factory is not callable',
+      )
+    },
+  }
+}
+
+/** All 40 v3 metadata codecs, in catalog order. */
+export const cipherstashV3CodecMetadataInstances: readonly CipherstashCodecMetadata[] =
+  [...V3_DOMAIN_META_BY_CODEC_ID.entries()].map(([codecId, meta]) => {
+    const typeName = envelopeTypeNameForCastAs(meta.castAs)
+    return new CipherstashCodecMetadata(
+      makeV3MetadataDescriptor(codecId, meta, typeName),
+      typeName,
+    )
+  })
+
+/** Pack-meta `types.storage` rows for the v3 codecs — one per domain,
+ * each targeting its own concrete `public.eql_v3_*` native type. */
+export const cipherstashV3StorageRows: ReadonlyArray<{
+  readonly typeId: string
+  readonly familyId: 'sql'
+  readonly targetId: 'postgres'
+  readonly nativeType: string
+}> = [...V3_DOMAIN_META_BY_CODEC_ID.entries()].map(([codecId, meta]) => ({
+  typeId: codecId,
+  familyId: 'sql',
+  targetId: 'postgres',
+  nativeType: meta.nativeType,
+}))

packages/prisma-next/src/extension-metadata/descriptor-meta.ts

@@ -29,6 +29,8 @@ import {
   cipherstashDoubleCodecMetadata,
   cipherstashJsonCodecMetadata,
   cipherstashStringCodecMetadata,
+  cipherstashV3CodecMetadataInstances,
+  cipherstashV3StorageRows,
 } from './codec-metadata'
 import {
   CIPHERSTASH_BIGINT_CODEC_ID,
@@ -62,6 +64,8 @@ export const cipherstashPackMeta = {
         cipherstashDateCodecMetadata,
         cipherstashBooleanCodecMetadata,
         cipherstashJsonCodecMetadata,
+        // EQL v3 — all 40 catalog domains, derived (see codec-metadata.ts).
+        ...cipherstashV3CodecMetadataInstances,
       ],
       // Drives the contract emitter to add
       //   `import type { CodecTypes as CipherstashTypes } from '@prisma-next/extension-cipherstash/codec-types'`
@@ -113,6 +117,14 @@ export const cipherstashPackMeta = {
           named: 'EncryptedJson',
           alias: 'EncryptedJson',
         },
+        // v3-only envelope (every numeric v3 domain renders as
+        // `EncryptedNumber`; the other v3 domains reuse the
+        // version-neutral envelope classes already imported above).
+        {
+          package: '@prisma-next/extension-cipherstash/runtime',
+          named: 'EncryptedNumber',
+          alias: 'EncryptedNumber',
+        },
       ],
     },
     queryOperationTypes: {
@@ -159,6 +171,9 @@ export const cipherstashPackMeta = {
         targetId: 'postgres',
         nativeType: EQL_V2_ENCRYPTED_TYPE,
       },
+      // EQL v3 — one row per catalog domain, each targeting its own
+      // concrete `public.eql_v3_*` native type (see codec-metadata.ts).
+      ...cipherstashV3StorageRows,
     ],
   },
 } as const

packages/prisma-next/src/v3/sdk-adapter-v3.ts

@@ -218,6 +218,7 @@ export function createCipherstashV3Sdk(
         // `never` operands so the real client's GENERIC method satisfies
         // the structural surface (see the interface doc); the concrete
         // operand is re-widened at each call site.
+        // biome-ignore lint/plugin: deliberate bridge into the structural `never`-operand surface (rationale above)
         const result = await client.encryptQuery(terms as never)
         const data = unwrap(result, `encryptQuery(${queryType})`)
         if (data.length !== group.length) {
@@ -244,6 +245,7 @@ export function createCipherstashV3Sdk(
       await Promise.all(
         jsonTerms.map(async (slot) => {
           // Cast rationale: see the scalar branch above.
+          // biome-ignore lint/plugin: deliberate bridge into the structural `never`-operand surface (rationale above)
           const result = await client.encryptQuery(
             slot.plaintext as never,
             { table, column, queryType: 'searchableJson' } as never,
@@ -274,7 +276,15 @@ export function createCipherstashV3Sdk(
         data: ensureV3Payload(data, 'bulkDecrypt', index),
       }))
       const result = await client.bulkDecrypt(payload)
-      return unwrap(result, 'bulkDecrypt').map((entry) => {
+      const data = unwrap(result, 'bulkDecrypt')
+      // Same cardinality contract as bulkEncrypt above: a truncated
+      // response would silently misalign plaintexts with `ciphertexts`.
+      if (data.length !== ciphertexts.length) {
+        throw new Error(
+          `cipherstash v3 bulkDecrypt: client returned ${data.length} plaintexts for ${ciphertexts.length} ciphertexts.`,
+        )
+      }
+      return data.map((entry) => {
         if ('error' in entry && entry.error !== undefined) {
           throw new Error(
             `cipherstash v3 bulkDecrypt entry failed: ${String(entry.error)}`,

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

@@ -28,16 +28,27 @@ function bigintSafeReplacer(_key: string, value: unknown): unknown {
 /** Serialise an EQL payload to plain JSONB text; `null`/`undefined` → `null`. */
 export function v3ToDriver(value: unknown): string | null {
   if (value === null || value === undefined) return null
-  return JSON.stringify(value, bigintSafeReplacer)
+  // `JSON.stringify` returns `undefined` for unsupported top-level values
+  // (a function, a symbol, a lone `undefined` survivor of the replacer);
+  // coerce that branch to `null` so the declared contract holds.
+  return JSON.stringify(value, bigintSafeReplacer) ?? null
 }
 
 /**
  * Parse a JSONB wire back to the EQL payload. Text wires are
  * `JSON.parse`d; objects (drivers that pre-parse jsonb) pass through;
- * `null`/`undefined` are preserved as-is.
+ * `null`/`undefined` are preserved as-is — the overloads keep that
+ * passthrough visible to callers (a nullable input yields a nullable
+ * result) instead of laundering `null` into `T`.
  */
-export function v3FromDriver<T>(value: string | object | null | undefined): T {
-  if (value === null || value === undefined) return value as T
+export function v3FromDriver<T>(value: string | object): T
+export function v3FromDriver<T>(
+  value: string | object | null | undefined,
+): T | null | undefined
+export function v3FromDriver<T>(
+  value: string | object | null | undefined,
+): T | null | undefined {
+  if (value === null || value === undefined) return value
   if (typeof value === 'object') return value as T
   return JSON.parse(value) as T
 }

packages/prisma-next/test/bundling-isolation.test.ts

@@ -188,6 +188,21 @@ const V3_WIRE_MARKERS = [
   'bulkEncryptMiddlewareV3',
 ] as const
 
+/**
+ * The six v2 codec-RUNTIME factories (all built on the composite wire's
+ * `makeCipherstashCellCodec`). Distinct from {@link V2_WIRE_MARKERS} so
+ * the v3-graph scans can name exactly which factory leaked, and safe as
+ * substrings: no v3 identifier contains any of them.
+ */
+const V2_CODEC_FACTORY_MARKERS = [
+  'createCipherstashStringCodec',
+  'createCipherstashDoubleCodec',
+  'createCipherstashBigIntCodec',
+  'createCipherstashDateCodec',
+  'createCipherstashBooleanCodec',
+  'createCipherstashJsonCodec',
+] as const
+
 interface ChunkFile {
   readonly file: string
   readonly body: string
@@ -250,6 +265,45 @@ function isAllowedSharedChunk(chunk: string): boolean {
   )
 }
 
+/**
+ * Scan an entry's COMPLETE import graph (entry body + every transitive
+ * chunk) for forbidden markers, returning `"<chunk> → <marker>"`
+ * diagnostics so a failure names the offending chunk, not just the
+ * entry. `exempt` skips known-safe chunks (with the invariant that the
+ * exemption itself is pinned elsewhere — see the call sites).
+ */
+function findLeaksInGraph(
+  entry: string,
+  forbidden: readonly string[],
+  exempt: (chunk: ChunkFile) => boolean = () => false,
+): string[] {
+  const leaks: string[] = []
+  for (const [file, chunk] of collectGraph(entry)) {
+    if (exempt(chunk)) continue
+    for (const marker of forbidden) {
+      if (chunk.body.includes(marker)) {
+        leaks.push(`${file} → ${marker}`)
+      }
+    }
+  }
+  return leaks
+}
+
+/**
+ * The version-neutral execution chunk — envelope base/classes, routing,
+ * abort, `stampRoutingKeysFromAst` — is legitimately reachable from
+ * EVERY entry (the v3 middleware imports the shared routing walk), and
+ * it currently also DEFINES the v2 wire encoder. Identified by CONTENT
+ * (it is the one chunk that defines the envelope base class), never by
+ * tsup's hash-named file. It is exempted ONLY from the v2-wire-marker
+ * scan of the v3 graph; the per-chunk "no chunk mixes the two wires"
+ * test below still pins that this chunk never gains a v3 wire marker,
+ * so the exemption cannot hide a fused chunk.
+ */
+function definesVersionNeutralExecutionChunk(chunk: ChunkFile): boolean {
+  return /var EncryptedEnvelopeBase\s*=/.test(chunk.body)
+}
+
 describe('bundling isolation', () => {
   it('dist entry files exist (run `pnpm --filter @cipherstash/prisma-next build` first)', () => {
     for (const entry of ENTRY_FILES) {
@@ -298,39 +352,39 @@ describe('bundling isolation', () => {
     expect(leaks, `v3 entry leaks: ${leaks.join(', ')}`).toEqual([])
   })
 
-  it('v3.js does not pull the v2 composite-literal wire', () => {
-    const entry = readChunk('v3.js')
-    const leaks = findLeaksInEntry(entry, V2_WIRE_MARKERS)
-    expect(leaks, `v3 entry leaks v2 wire: ${leaks.join(', ')}`).toEqual([])
+  it('no chunk in the v3 graph references the v2 composite-literal wire (version-neutral execution chunk exempted)', () => {
+    // COMPLETE-graph scan, not just the entry body: a cross-plane leak
+    // usually arrives through a transitive chunk import, which an
+    // entry-body substring check never sees. `v3.js` legitimately
+    // shares the version-neutral execution chunk (envelope
+    // base/classes, routing, abort, `stampRoutingKeysFromAst`) with the
+    // v2 entries — that chunk currently also DEFINES the v2 wire
+    // encoder, so it is exempted here by content and pinned against v3
+    // contamination by the per-chunk disjointness test below.
+    const leaks = findLeaksInGraph(
+      'v3.js',
+      V2_WIRE_MARKERS,
+      definesVersionNeutralExecutionChunk,
+    )
+    expect(leaks, `v3 graph leaks v2 wire: ${leaks.join(', ')}`).toEqual([])
   })
 
-  it('the v3 entry graph never reaches the v2 codec-runtime chunk', () => {
-    // `v3.js` legitimately shares the version-neutral execution chunk
-    // (envelope base/classes, routing, abort, `stampRoutingKeysFromAst`)
-    // with the v2 entries — that chunk currently also DEFINES the v2
-    // wire encoder, which the per-chunk disjointness test below pins.
-    // What must never happen is the v3 graph importing the v2
-    // codec-RUNTIME chunk (the six `createCipherstash*Codec` factories
-    // built on the composite wire).
-    const v3Chunks = collectGraph('v3.js')
-    const offenders = [...v3Chunks.entries()]
-      .filter(([file]) => file !== 'v3.js')
-      .filter(([, chunk]) =>
-        chunk.body.includes('createCipherstashStringCodec'),
-      )
-      .map(([file]) => file)
+  it('no chunk in the v3 graph references any v2 codec-runtime factory', () => {
+    // All six `createCipherstash*Codec` factories (built on the
+    // composite wire), against every chunk in the v3 graph — including
+    // the version-neutral execution chunk, which must never grow one.
+    const leaks = findLeaksInGraph('v3.js', V2_CODEC_FACTORY_MARKERS)
     expect(
-      offenders,
-      `v3 graph reaches v2 codec-runtime chunk(s): ${offenders.join(', ')}`,
+      leaks,
+      `v3 graph reaches v2 codec-runtime factories: ${leaks.join(', ')}`,
     ).toEqual([])
   })
 
-  it('middleware.js (v2 bulk-encrypt entry) does not pull the v3 wire plane', () => {
-    const entry = readChunk('middleware.js')
-    const leaks = findLeaksInEntry(entry, V3_WIRE_MARKERS)
+  it('no chunk in the middleware.js graph (v2 bulk-encrypt entry) references the v3 wire plane', () => {
+    const leaks = findLeaksInGraph('middleware.js', V3_WIRE_MARKERS)
     expect(
       leaks,
-      `middleware entry leaks v3 wire: ${leaks.join(', ')}`,
+      `middleware graph leaks v3 wire: ${leaks.join(', ')}`,
     ).toEqual([])
   })