docs(prisma-next): document EQL v3 String support

Author: tobyhede

packages/prisma-next/DEVELOPING.md

@@ -41,12 +41,18 @@ packages/3-extensions/cipherstash/
     │   └── descriptor-meta.ts        cipherstashPackMeta + authoring + storage + codec instances
     ├── middleware/
     │   └── bulk-encrypt.ts           bulkEncryptMiddleware(sdk) + stampRoutingKeysFromAst
+    ├── v3/                           EQL v3 (domain-based; text/String scalar)
+    │   ├── domain-map.ts             (scalar, index) → eql_v3 domain SSOT
+    │   └── wire-codec.ts             plain-jsonb wire (encode/decodeEqlV3Wire)
     ├── migration/
     │   ├── codec-hooks-factory.ts    makeCipherstashCodecHooks({...}) factory (per codec)
+    │   ├── codec-hooks-v3.ts         v3 hooks: expandNativeType → per-index domain
     │   ├── cipherstash-codec.ts      cipherstashStringCodecHooks string-only hook bundle
     │   ├── call-classes.ts           CipherstashAddSearchConfigCall / RemoveSearchConfigCall
-    │   ├── eql-bundle.ts             EQL install SQL (vendored byte-for-byte)
-    │   └── eql-install.generated.ts  generated EQL install op definitions
+    │   ├── eql-bundle.ts             EQL v2 install SQL (vendored byte-for-byte)
+    │   ├── eql-install.generated.ts  generated EQL v2 install op definitions
+    │   ├── eql-v3-bundle.ts          EQL v3 install SQL (vendored byte-for-byte)
+    │   └── eql-v3-install.generated.ts  GENERATED — see scripts/REFRESH_EQL_V3.md
     ├── types/
     │   ├── codec-types.ts            CipherstashCodecTypes interface (decode return types)
     │   └── operation-types.ts        QueryOperationTypes augmentation (column-method surface)

packages/prisma-next/README.md

@@ -94,12 +94,39 @@ See the [full documentation](https://cipherstash.com/docs/stack/cipherstash/encr
 | `./stack`        | One-call setup against `@cipherstash/stack`: `cipherstashFromStack`, `deriveStackSchemas`, `createCipherstashSdk` |
 | `./control`      | `SqlControlExtensionDescriptor` (contract space + pack meta + codec lifecycle hooks)                   |
 | `./runtime`      | Six envelope classes + `CipherstashSdk` + codec runtime + `decryptAll` + four free-standing helpers    |
-| `./middleware`   | `bulkEncryptMiddleware(sdk)`                                                                           |
+| `./middleware`   | `bulkEncryptMiddleware(sdk)` (v2) + `bulkEncryptV3Middleware(sdk)` (v3)                                |
 | `./pack`         | `cipherstashPackMeta` for TS contract authoring                                                        |
-| `./column-types` | Six TS factories: `encryptedString` / `encryptedDouble` / `encryptedBigInt` / `encryptedDate` / `encryptedBoolean` / `encryptedJson` |
+| `./column-types` | TS factories: `encryptedString` / `encryptedDouble` / `encryptedBigInt` / `encryptedDate` / `encryptedBoolean` / `encryptedJson` (v2) + `encryptedStringV3` (v3) |
 
 `./control`, `./runtime`, and `./middleware` are tree-shakable. `./stack` sits on top of `./runtime` + `./middleware` and additionally pulls in `@cipherstash/stack`; consumers who implement `CipherstashSdk` against a different KMS skip `./stack` and pay no `@cipherstash/stack` bundle cost.
 
+## EQL v3 (experimental)
+
+EQL v3 is a **domain-based** encryption model that coexists with v2: v2 columns keep their `eql_v2_encrypted` storage and SQL, and v3 columns are added independently. Milestone 1 supports the **`String`/`text`** scalar only.
+
+A v3 column declares **exactly one index capability** (one Postgres domain) via `EncryptedStringV3`:
+
+```prisma
+model Doc {
+  id    String @id
+  email cipherstash.EncryptedStringV3({ index: "equality" })       // → eql_v3.text_eq
+  bio   cipherstash.EncryptedStringV3({ index: "freeTextSearch" }) // → eql_v3.text_match
+  name  cipherstash.EncryptedStringV3({ index: "orderAndRange" })  // → eql_v3.text_ord
+}
+```
+
+…or in TypeScript: `encryptedStringV3({ index: 'equality' })`.
+
+**Operators per index** (the v3 column carries the cipherstash traits, so the same `cipherstash*` operator surface attaches; the column's single index decides which are valid):
+
+| Index             | Domain             | Valid operators                                                                   |
+| ----------------- | ------------------ | --------------------------------------------------------------------------------- |
+| `equality`        | `eql_v3.text_eq`   | `cipherstashEq` / `cipherstashNe` / `cipherstashInArray` / `cipherstashNotInArray` |
+| `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.
+
 ## Authentication
 
 There are 2 main ways to authenticate to CipherStash: