feat(prisma-next): wire v3 into runtime/control descriptors + exports

Register the v3 codec hooks + v3 baseline migration in the control descriptor,
add bulkEncryptV3Middleware to cipherstashFromStack, re-export the v3 surface from
runtime/middleware, and advance the head ref to the union of baseline invariants.

Author: tobyhede

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

@@ -0,0 +1,21 @@
+{
+  "from": null,
+  "to": "sha256:efa685171bebbb8f078f08d12be3578bb5d96b71669dccc6cc9e4be96af8cdb4",
+  "labels": [],
+  "providedInvariants": [
+    "cipherstash:install-eql-v3-bundle-v1"
+  ],
+  "createdAt": "2026-06-16T23:32:09.463Z",
+  "fromContract": null,
+  "toContract": {
+    "storage": {
+      "storageHash": "sha256:efa685171bebbb8f078f08d12be3578bb5d96b71669dccc6cc9e4be96af8cdb4"
+    }
+  },
+  "hints": {
+    "used": [],
+    "applied": [],
+    "plannerVersion": "2.0.0"
+  },
+  "migrationHash": "sha256:997f0460ad5ad14530144f6c031104966b7cf90052ebf794cc2cf0f7c264e0ee"
+}

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

@@ -22,9 +22,15 @@ const INSTALL_LABEL = 'Install EQL v3 bundle (eql_v3 schema, text domains, index
 
 export default class M extends Migration {
   override describe() {
+    // The v3 bundle installs the eql_v3 schema/domains/functions but adds NO
+    // contract-IR object (no tables modelled), so the resulting storage hash is
+    // unchanged from the v2 baseline — `to` equals the package's contract
+    // storageHash. v3 is therefore a parallel install baseline (from: null)
+    // satisfying its own invariant; the head ref's invariant set is the union of
+    // both baselines.
     return {
       from: null,
-      to: 'cipherstash:eql-v3-baseline',
+      to: 'sha256:efa685171bebbb8f078f08d12be3578bb5d96b71669dccc6cc9e4be96af8cdb4',
     };
   }
 

packages/prisma-next/migrations/refs/head.json

@@ -1,4 +1,4 @@
 {
   "hash": "sha256:efa685171bebbb8f078f08d12be3578bb5d96b71669dccc6cc9e4be96af8cdb4",
-  "invariants": ["cipherstash:install-eql-bundle-v1"]
+  "invariants": ["cipherstash:install-eql-bundle-v1", "cipherstash:install-eql-v3-bundle-v1"]
 }

packages/prisma-next/src/exports/control.ts

@@ -38,6 +38,12 @@ import baselineMetadata from '../../migrations/20260601T0000_install_eql_bundle/
 import baselineOps from '../../migrations/20260601T0000_install_eql_bundle/ops.json' with {
   type: 'json',
 };
+import baselineV3Metadata from '../../migrations/20260601T0100_install_eql_v3_bundle/migration.json' with {
+  type: 'json',
+};
+import baselineV3Ops from '../../migrations/20260601T0100_install_eql_v3_bundle/ops.json' with {
+  type: 'json',
+};
 import headRef from '../../migrations/refs/head.json' with { type: 'json' };
 import contractJson from '../contract.json' with { type: 'json' };
 import {
@@ -48,6 +54,8 @@ import {
   CIPHERSTASH_DOUBLE_CODEC_ID,
   CIPHERSTASH_JSON_CODEC_ID,
   CIPHERSTASH_STRING_CODEC_ID,
+  CIPHERSTASH_STRING_V3_CODEC_ID,
+  CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
 } from '../extension-metadata/constants';
 import { cipherstashPackMeta } from '../extension-metadata/descriptor-meta';
 import {
@@ -58,6 +66,7 @@ import {
   cipherstashJsonCodecHooks,
   cipherstashStringCodecHooks,
 } from '../migration/cipherstash-codec';
+import { cipherstashStringV3CodecHooks } from '../migration/codec-hooks-v3';
 
 const cipherstashContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
   contractJson,
@@ -67,6 +76,12 @@ const cipherstashContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({
       metadata: baselineMetadata,
       ops: baselineOps,
     },
+    {
+      // EQL v3 baseline — installs the eql_v3 bundle. Sorts after the v2 baseline.
+      dirName: CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
+      metadata: baselineV3Metadata,
+      ops: baselineV3Ops,
+    },
   ],
   headRef,
 });
@@ -98,6 +113,8 @@ const cipherstashExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'>
         [CIPHERSTASH_DATE_CODEC_ID]: cipherstashDateCodecHooks,
         [CIPHERSTASH_BOOLEAN_CODEC_ID]: cipherstashBooleanCodecHooks,
         [CIPHERSTASH_JSON_CODEC_ID]: cipherstashJsonCodecHooks,
+        // v3: expandNativeType → per-index domain; onFieldEvent emits no search-config.
+        [CIPHERSTASH_STRING_V3_CODEC_ID]: cipherstashStringV3CodecHooks,
       },
     },
   },

packages/prisma-next/src/exports/middleware.ts

@@ -22,3 +22,6 @@
  */
 
 export { bulkEncryptMiddleware } from '../middleware/bulk-encrypt';
+// EQL v3 storage-vs-search-term split middleware. Register ALONGSIDE
+// bulkEncryptMiddleware (disjoint codec-id sets — each ignores the other's params).
+export { bulkEncryptV3Middleware } from '../middleware/bulk-encrypt-v3';

packages/prisma-next/src/exports/runtime.ts

@@ -43,6 +43,7 @@ export {
   createCipherstashDoubleCodec,
   createCipherstashJsonCodec,
   createCipherstashStringCodec,
+  createCipherstashStringV3Codec,
 } from '../execution/codec-runtime';
 export type { DecryptAllOptions } from '../execution/decrypt-all';
 export { decryptAll } from '../execution/decrypt-all';
@@ -82,13 +83,15 @@ export {
   cipherstashJsonbGet,
   cipherstashJsonbPathQueryFirst,
 } from '../execution/helpers';
+export { queryTypeForIndex } from '../execution/operators';
 export type {
   CipherstashAnyParams,
   CipherstashBooleanParams,
   CipherstashDateParams,
   CipherstashJsonParams,
   CipherstashNumericParams,
   CipherstashStringParams,
+  CipherstashStringV3Params,
 } from '../execution/parameterized';
 export {
   createParameterizedCodecDescriptors,
@@ -98,26 +101,31 @@ export {
   encryptedDoubleParamsSchema,
   encryptedJsonParamsSchema,
   encryptedStringParamsSchema,
+  encryptedStringV3ParamsSchema,
   renderEncryptedBigIntOutputType,
   renderEncryptedBooleanOutputType,
   renderEncryptedDateOutputType,
   renderEncryptedDoubleOutputType,
   renderEncryptedJsonOutputType,
   renderEncryptedStringOutputType,
+  renderEncryptedStringV3OutputType,
 } from '../execution/parameterized';
 export type {
   CipherstashBulkDecryptArgs,
   CipherstashBulkEncryptArgs,
+  CipherstashBulkEncryptQueryArgs,
   CipherstashRoutingKey,
   CipherstashSdk,
   CipherstashSingleDecryptArgs,
 } from '../execution/sdk';
+export type { V3DataType, V3Index } from '../v3/domain-map';
 export {
   CIPHERSTASH_BIGINT_CODEC_ID,
   CIPHERSTASH_BOOLEAN_CODEC_ID,
   CIPHERSTASH_DATE_CODEC_ID,
   CIPHERSTASH_DOUBLE_CODEC_ID,
   CIPHERSTASH_JSON_CODEC_ID,
+  CIPHERSTASH_STRING_V3_CODEC_ID,
 } from '../extension-metadata/constants';
 
 export { CIPHERSTASH_EXTENSION_VERSION };

packages/prisma-next/src/stack/from-stack.ts

@@ -36,6 +36,7 @@ import type { SqlMiddleware, SqlRuntimeExtensionDescriptor } from '@prisma-next/
 
 import { createCipherstashRuntimeDescriptor } from '../exports/runtime'
 import { bulkEncryptMiddleware } from '../middleware/bulk-encrypt'
+import { bulkEncryptV3Middleware } from '../middleware/bulk-encrypt-v3'
 import {
   type ContractStorageView,
   deriveStackSchemas,
@@ -91,7 +92,10 @@ export async function cipherstashFromStack(
 
   return {
     extensions: [createCipherstashRuntimeDescriptor({ sdk })],
-    middleware: [bulkEncryptMiddleware(sdk)],
+    // Two middlewares over one sdk: v2 filters CIPHERSTASH_CODEC_ID_SET, v3 filters
+    // CIPHERSTASH_V3_CODEC_ID_SET — disjoint, so order is irrelevant and each ignores
+    // the other's params.
+    middleware: [bulkEncryptMiddleware(sdk), bulkEncryptV3Middleware(sdk)],
     encryptionClient,
   }
 }

packages/prisma-next/test/descriptor.test.ts

@@ -29,6 +29,7 @@ import {
   CIPHERSTASH_BASELINE_MIGRATION_NAME,
   CIPHERSTASH_INVARIANTS,
   CIPHERSTASH_SPACE_ID,
+  CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
   EQL_V2_CONFIGURATION_TABLE,
 } from '../src/extension-metadata/constants';
 import { EQL_BUNDLE_SQL } from '../src/migration/eql-bundle';
@@ -49,13 +50,19 @@ describe('cipherstash extension descriptor (contract-space package layout)', ()
     expect(Object.keys(space!.contractJson.storage.tables)).toEqual([EQL_V2_CONFIGURATION_TABLE]);
   });
 
-  it('publishes one baseline migration sourced from the on-disk emit pipeline', () => {
+  it('publishes the v2 + v3 baseline migrations sourced from the on-disk emit pipeline', () => {
     const space = cipherstashExtensionDescriptor.contractSpace!;
-    expect(space.migrations).toHaveLength(1);
+    expect(space.migrations).toHaveLength(2);
     const baseline = space.migrations[0]!;
     expect(baseline.dirName).toBe(CIPHERSTASH_BASELINE_MIGRATION_NAME);
     expect(baseline.metadata.from).toBeNull();
     expect(baseline.metadata.to).toBe(space.contractJson.storage.storageHash);
+    // The v3 baseline installs the eql_v3 bundle; it adds no contract-IR object,
+    // so it resolves to the SAME storage hash (a parallel install baseline).
+    const v3 = space.migrations[1]!;
+    expect(v3.dirName).toBe(CIPHERSTASH_V3_BASELINE_MIGRATION_NAME);
+    expect(v3.metadata.from).toBeNull();
+    expect(v3.metadata.to).toBe(space.contractJson.storage.storageHash);
   });
 
   it('baseline ops carry the installEqlBundle op + structural create-* ops', () => {
@@ -83,12 +90,13 @@ describe('cipherstash extension descriptor (contract-space package layout)', ()
     expect(installOp?.execute?.[0]?.sql).toBe(EQL_BUNDLE_SQL);
   });
 
-  it("points the head ref at the latest migration's destination hash", () => {
+  it("points the head ref at the baseline destination hash + the union of every baseline's invariants", () => {
     const space = cipherstashExtensionDescriptor.contractSpace!;
+    // Both baselines resolve to the same storage hash (v3 adds no IR object).
     expect(space.headRef.hash).toBe(space.migrations[0]!.metadata.to);
-    expect([...space.headRef.invariants].sort()).toEqual(
-      [...space.migrations[0]!.metadata.providedInvariants].sort(),
-    );
+    // The head invariant set is the union of all applied baselines' invariants.
+    const union = space.migrations.flatMap((m) => [...m.metadata.providedInvariants]).sort();
+    expect([...space.headRef.invariants].sort()).toEqual(union);
   });
 
   it('self-consistency check passes — headRef.hash matches re-derived storage hash', () => {

packages/prisma-next/test/v3/control-v3.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import cipherstashExtensionDescriptor from '../../src/exports/control'
+import {
+  CIPHERSTASH_STRING_V3_CODEC_ID,
+  CIPHERSTASH_V3_BASELINE_MIGRATION_NAME,
+} from '../../src/extension-metadata/constants'
+import { cipherstashStringV3CodecHooks } from '../../src/migration/codec-hooks-v3'
+
+describe('cipherstash control descriptor (v3)', () => {
+  it('registers cipherstashStringV3CodecHooks keyed by the v3 codec id', () => {
+    const hooks = (
+      cipherstashExtensionDescriptor as unknown as {
+        types: { codecTypes: { controlPlaneHooks: Record<string, unknown> } }
+      }
+    ).types.codecTypes.controlPlaneHooks
+    expect(hooks[CIPHERSTASH_STRING_V3_CODEC_ID]).toBe(cipherstashStringV3CodecHooks)
+  })
+
+  it('includes the v3 baseline migration in the contract space', () => {
+    const cs = (
+      cipherstashExtensionDescriptor as unknown as {
+        contractSpace: { migrations: ReadonlyArray<{ dirName: string }> }
+      }
+    ).contractSpace
+    expect(cs.migrations.map((m) => m.dirName)).toContain(CIPHERSTASH_V3_BASELINE_MIGRATION_NAME)
+  })
+})

packages/prisma-next/test/v3/exports.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { createCipherstashRuntimeDescriptor } from '../../src/exports/runtime'
+import { makeFakeSdk } from './helpers/fake-sdk'
+
+describe('v3 runtime descriptor', () => {
+  it('advertises the v3 string codec and the v3-capable operators', () => {
+    const desc = createCipherstashRuntimeDescriptor({ sdk: makeFakeSdk() })
+    expect(desc.codecs?.().map((c: { codecId: string }) => c.codecId)).toContain('cipherstash/string-v3@1')
+    // cipherstashEq attaches to the v3 codec via the shared cipherstash:string trait.
+    expect(Object.keys(desc.queryOperations?.() ?? {})).toContain('cipherstashEq')
+  })
+})
+
+describe('v3 public re-exports', () => {
+  it('exposes the v3 surface from @cipherstash/prisma-next/runtime', async () => {
+    const runtime = await import('../../src/exports/runtime')
+    expect(typeof runtime.createCipherstashStringV3Codec).toBe('function')
+    expect(typeof runtime.queryTypeForIndex).toBe('function')
+    expect(runtime.CIPHERSTASH_STRING_V3_CODEC_ID).toBe('cipherstash/string-v3@1')
+    expect(typeof runtime.encryptedStringV3ParamsSchema).toBe('function')
+    expect(typeof runtime.renderEncryptedStringV3OutputType).toBe('function')
+  })
+
+  it('exposes encryptedStringV3 from @cipherstash/prisma-next/column-types', async () => {
+    const columnTypes = await import('../../src/exports/column-types')
+    expect(typeof columnTypes.encryptedStringV3).toBe('function')
+  })
+
+  it('exposes bulkEncryptV3Middleware from @cipherstash/prisma-next/middleware', async () => {
+    const mw = await import('../../src/exports/middleware')
+    expect(typeof mw.bulkEncryptV3Middleware).toBe('function')
+  })
+})