feat(prisma-next): add v3 baseline migration + expandNativeType domain hook

migration.json/end-contract.* are regenerated by the framework contract-emit CLI
during e2e setup (Task 15); ops.json is generated here from the operations getter.

Author: tobyhede

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env -S node
+/**
+ * CipherStash EQL v3 baseline migration — install the vendored eql_v3 bundle.
+ *
+ * Mirrors the v2 baseline (`../20260601T0000_install_eql_bundle/migration.ts`)
+ * but installs the **eql_v3** bundle: the `eql_v3` schema, the `eql_v3.text*`
+ * domains (`text`, `text_eq`, `text_match`, `text_ord`), and the index-term
+ * extractor functions. The bundle flows in byte-for-byte under the
+ * `cipherstash:install-eql-v3-bundle-v1` invariant.
+ *
+ * Unlike v2, v3 emits NO `add_search_config` rows — the per-column domain type
+ * (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`.
+ */
+import { Migration, MigrationCLI, rawSql } from '@prisma-next/target-postgres/migration';
+import { CIPHERSTASH_INVARIANTS } from '../../src/extension-metadata/constants';
+import { EQL_V3_BUNDLE_SQL } from '../../src/migration/eql-v3-bundle';
+
+const INSTALL_LABEL = 'Install EQL v3 bundle (eql_v3 schema, text domains, index-term extractors)';
+
+export default class M extends Migration {
+  override describe() {
+    return {
+      from: null,
+      to: 'cipherstash:eql-v3-baseline',
+    };
+  }
+
+  override get operations() {
+    return [
+      rawSql({
+        id: 'cipherstash.install-eql-v3-bundle',
+        label: INSTALL_LABEL,
+        operationClass: 'additive',
+        invariantId: CIPHERSTASH_INVARIANTS.installBundleV3,
+        target: { id: 'postgres' },
+        precheck: [],
+        execute: [{ description: INSTALL_LABEL, sql: EQL_V3_BUNDLE_SQL }],
+        postcheck: [
+          {
+            description: 'verify "eql_v3" schema exists',
+            sql: "SELECT EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = 'eql_v3')",
+          },
+          {
+            description: 'verify "eql_v3.text_eq" domain exists',
+            sql: "SELECT EXISTS (SELECT 1 FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace WHERE n.nspname = 'eql_v3' AND t.typname = 'text_eq')",
+          },
+        ],
+      }),
+    ];
+  }
+}
+
+MigrationCLI.run(import.meta.url, M);

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

@@ -0,0 +1,38 @@
+/**
+ * `CodecControlHooks` for the EQL v3 string codec.
+ *
+ * v3 diverges from the v2 hooks factory in two ways:
+ *
+ *   - **`expandNativeType` is NOT identity.** A v3 column's DDL type is the
+ *     per-index domain (`eql_v3.text_eq` / `text_match` / `text_ord`), derived
+ *     from `typeParams.index`. The base `eql_v3.text` is narrowed here at plan
+ *     time — this is what makes the column's domain CHECK enforce the chosen
+ *     index capability.
+ *   - **`onFieldEvent` emits NO `add_search_config`.** In v2 the search capability
+ *     is wired by `eql_v2.add_search_config` rows; in v3 the domain type itself
+ *     encodes the capability (applied via `expandNativeType`), so no config rows
+ *     are emitted on add/drop/alter.
+ */
+
+import type { CodecControlHooks } from '@prisma-next/family-sql/control'
+import { type V3Index, eqlV3Domain } from '../v3/domain-map'
+
+const V3_INDEX_VALUES = ['equality', 'freeTextSearch', 'orderAndRange'] as const
+
+function isV3Index(value: unknown): value is V3Index {
+  return typeof value === 'string' && (V3_INDEX_VALUES as readonly string[]).includes(value)
+}
+
+const expandNativeType: NonNullable<CodecControlHooks['expandNativeType']> = ({ typeParams }) => {
+  const index = typeParams?.['index']
+  // Per-index domain when the column declares one (it always does); fall back to
+  // the base storage domain otherwise so the hook never throws on a degenerate ctx.
+  return eqlV3Domain('text', isV3Index(index) ? index : undefined)
+}
+
+export const cipherstashStringV3CodecHooks: CodecControlHooks = {
+  // v3 capability is encoded by the domain type (expandNativeType), not by
+  // add_search_config rows — so no field-event ops are emitted.
+  onFieldEvent: () => [],
+  expandNativeType,
+}

packages/prisma-next/src/migration/codec-hooks-v3.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { cipherstashStringV3CodecHooks } from '../../src/migration/codec-hooks-v3'
+
+describe('cipherstashStringV3CodecHooks.expandNativeType', () => {
+  const expand = cipherstashStringV3CodecHooks.expandNativeType!
+
+  it('returns the per-index domain for the column', () => {
+    expect(expand({ nativeType: 'eql_v3.text', typeParams: { index: 'equality' } })).toBe('eql_v3.text_eq')
+    expect(expand({ nativeType: 'eql_v3.text', typeParams: { index: 'freeTextSearch' } })).toBe('eql_v3.text_match')
+    expect(expand({ nativeType: 'eql_v3.text', typeParams: { index: 'orderAndRange' } })).toBe('eql_v3.text_ord')
+  })
+
+  it('falls back to the base storage domain when no index is present', () => {
+    expect(expand({ nativeType: 'eql_v3.text' })).toBe('eql_v3.text')
+  })
+})
+
+describe('cipherstashStringV3CodecHooks.onFieldEvent', () => {
+  it('emits NO ops on field add (the domain encodes the capability — no add_search_config)', () => {
+    const ops = cipherstashStringV3CodecHooks.onFieldEvent!('added', {
+      tableName: 'user_v3',
+      fieldName: 'email',
+      newField: { typeParams: { index: 'equality' } },
+    } as never)
+    expect(ops).toEqual([])
+  })
+})

packages/prisma-next/test/v3/codec-hooks-v3.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import migrationV3 from '../../migrations/20260601T0100_install_eql_v3_bundle/migration'
+import { CIPHERSTASH_INVARIANTS } from '../../src/extension-metadata/constants'
+import { EQL_V3_BUNDLE_SQL } from '../../src/migration/eql-v3-bundle'
+
+describe('v3 baseline migration', () => {
+  it('installs the v3 bundle byte-for-byte under the v3 invariant', () => {
+    const ops = new (migrationV3 as unknown as new () => { operations: ReadonlyArray<Record<string, unknown>> })().operations
+    const op = ops[0] as {
+      invariantId: string
+      execute: ReadonlyArray<{ sql: string }>
+    }
+    expect(op.invariantId).toBe(CIPHERSTASH_INVARIANTS.installBundleV3)
+    expect(op.execute[0]!.sql).toBe(EQL_V3_BUNDLE_SQL)
+  })
+
+  it('postchecks the eql_v3 schema + text_eq domain', () => {
+    const ops = new (migrationV3 as unknown as new () => { operations: ReadonlyArray<Record<string, unknown>> })().operations
+    const op = ops[0] as { postcheck: ReadonlyArray<{ sql: string }> }
+    const sqls = op.postcheck.map((p) => p.sql).join('\n')
+    expect(sqls).toContain('eql_v3')
+    expect(sqls).toContain('text_eq')
+  })
+})