feat(prisma-next): v3 per-domain authoring constructors + *V2 aliases

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

Author: 2 people

packages/prisma-next/src/contract-authoring.ts

@@ -1,24 +1,35 @@
 /**
  * TS contract factories for cipherstash-encrypted columns.
  *
- * Counterparts to the PSL constructors `cipherstash.Encrypted<Type>({...})`
- * registered in `../contract-authoring`. The six factories
- * (`encryptedString`, `encryptedDouble`, `encryptedBigInt`,
- * `encryptedDate`, `encryptedBoolean`, `encryptedJson`) produce the
- * same `ColumnTypeDescriptor` shape as their PSL counterparts, so
- * PSL- and TS-authored contracts emit byte-identical `contract.json`.
- * Pinned by the parity fixtures at
- * `test/integration/test/authoring/parity/cipherstash-encrypted-{string,double,bigint,date,boolean,json}/`.
+ * ## v3: one factory per exposed domain
  *
- * Every search-mode flag defaults to `true` — searchable encryption
- * is the legitimate default for an extension whose entire reason for
- * existing is to make encrypted columns queryable. Users who want
- * storage-only encryption opt out explicitly:
- * `encryptedString({ equality: false, freeTextSearch: false, orderAndRange: false })`.
- * Mirrors the PSL constructors' `true` defaults declared via
+ * Counterparts to the argument-less PSL constructors
+ * `cipherstash.Encrypted<Stem><Suffix>()` registered in
+ * `../contract-authoring`. Each factory returns the domain's concrete
+ * descriptor — static codec id, `public.eql_v3_*` native type, and a static
+ * `{ castAs, capabilities }` typeParams block — identical to what its PSL
+ * counterpart lowers to, so PSL- and TS-authored contracts emit
+ * byte-identical `contract.json`. There are NO options: the factory IS the
+ * capability set (`encryptedTextSearch` vs `encryptedText`, and so on).
+ *
+ * ## v2: legacy `*V2` aliases
+ *
+ * The six pre-rename factories (`encryptedStringV2`, `encryptedDoubleV2`,
+ * `encryptedBigIntV2`, `encryptedDateV2`, `encryptedBooleanV2`,
+ * `encryptedJsonV2`) keep their previous bodies verbatim: single optional
+ * options object, every search-mode flag defaulting to `true` — searchable
+ * encryption is the legitimate default for an extension whose entire reason
+ * for existing is to make encrypted columns queryable — and the
+ * `cipherstash/*@1` codec + `eql_v2_encrypted` native type outputs. They
+ * mirror the `*V2` PSL constructors' `true` defaults declared via
  * `AuthoringArgRef.default`.
  */
 
+import {
+  type AnyEncryptedV3Column,
+  stripDomainSchema,
+  types,
+} from '@cipherstash/stack/eql/v3'
 import {
   CIPHERSTASH_BIGINT_CODEC_ID,
   CIPHERSTASH_BOOLEAN_CODEC_ID,
@@ -28,9 +39,131 @@ import {
   CIPHERSTASH_STRING_CODEC_ID,
   EQL_V2_ENCRYPTED_TYPE,
 } from '../extension-metadata/constants'
+import { toV3CodecId, type V3CastAs } from '../v3/catalog'
+
+// ---------------------------------------------------------------------------
+// v3 factories (derived from the concrete stack columns)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-column literal inference via the getters, NOT `EncryptedV3Column<infer D>`:
+ * the stack's bundled `.d.ts` drops the private `definition` field's type, so
+ * inferring through the class widens to the constraint. The getters' declared
+ * return types survive d.ts bundling (see
+ * `../extension-metadata/constants-v3.ts` for the full rationale).
+ */
+type EqlTypeFromGetter<C> = C extends { getEqlType(): infer T extends string }
+  ? T
+  : never
+type CapabilitiesFromGetter<C> = C extends { getQueryCapabilities(): infer T }
+  ? T
+  : never
+
+type StripPublic<T extends string> = T extends `public.${infer D}` ? D : never
+
+/**
+ * Literal-preserving authoring descriptor, generic over the concrete stack
+ * column `C`. `codecId`, `nativeType`, and `capabilities` are the domain's
+ * LITERAL types (not `string` / `unknown`), so two domains' factories are
+ * mutually non-assignable — this is the type spine (design "Type Discipline").
+ * `castAs` is the one field the stack widens (`build(): ColumnSchema`), which
+ * is harmless: `nativeType` already discriminates every domain. Pinned by the
+ * type-level tests in `test/v3/column-types.test-d.ts`.
+ */
+export interface V3ColumnDescriptor<C extends AnyEncryptedV3Column> {
+  readonly codecId: `cipherstash/eql-v3/${StripPublic<EqlTypeFromGetter<C>>}@1`
+  readonly nativeType: EqlTypeFromGetter<C>
+  readonly typeParams: {
+    readonly castAs: V3CastAs
+    readonly capabilities: CapabilitiesFromGetter<C>
+  }
+}
+
+/**
+ * Build one authoring factory from a concrete stack `types.*` factory. VALUES
+ * are read from the column (`getEqlType` / `getQueryCapabilities` / `build`) —
+ * nothing is hardcoded — and the codec id goes through the catalog's
+ * `toV3CodecId` (registry key VERBATIM, never a name transform), while the
+ * literal TYPES flow from `C`. The factory set is a typed 1:1 mirror of the
+ * exposed catalog domains, which is how "derive from the catalog" and
+ * "distinct static type per domain" coexist: TypeScript cannot hand distinct
+ * static types to values pulled from a runtime record, so each factory names
+ * its stack factory. Drift is caught by the 1:1 runtime test in
+ * `test/column-types.test.ts` (exposed factory set === catalog minus
+ * `*_ord_ore`) and the catalog drift tests.
+ */
+function v3Authored<C extends AnyEncryptedV3Column>(
+  make: (name: string) => C,
+): () => V3ColumnDescriptor<C> {
+  const probe = make('__probe__')
+  const nativeType = probe.getEqlType()
+  const descriptor = {
+    codecId: toV3CodecId(stripDomainSchema(nativeType)),
+    nativeType,
+    typeParams: {
+      // Narrowing assertion, mirrors ../v3/catalog.ts: `build()` widens
+      // `cast_as` in the bundled d.ts; the value is the domain's literal.
+      castAs: probe.build().cast_as as V3CastAs,
+      capabilities: probe.getQueryCapabilities(),
+    },
+    // Narrowing assertion: runtime strings are the literals the getters
+    // declare; `toV3CodecId` returns `string` by signature.
+  } as V3ColumnDescriptor<C>
+  return () => descriptor
+}
+
+// Each factory has a DISTINCT return type (V3ColumnDescriptor<EncryptedXColumn>);
+// `encryptedBigIntOrd()` is not assignable to `encryptedText()` and vice-versa.
+// Note the stack factory names: bigint is `types.Bigint*` (not `BigInt*`).
+// text family
+export const encryptedText = v3Authored(types.Text)
+export const encryptedTextEq = v3Authored(types.TextEq)
+export const encryptedTextOrd = v3Authored(types.TextOrd)
+export const encryptedTextMatch = v3Authored(types.TextMatch)
+export const encryptedTextSearch = v3Authored(types.TextSearch)
+// integer
+export const encryptedInteger = v3Authored(types.Integer)
+export const encryptedIntegerEq = v3Authored(types.IntegerEq)
+export const encryptedIntegerOrd = v3Authored(types.IntegerOrd)
+// smallint
+export const encryptedSmallint = v3Authored(types.Smallint)
+export const encryptedSmallintEq = v3Authored(types.SmallintEq)
+export const encryptedSmallintOrd = v3Authored(types.SmallintOrd)
+// bigint
+export const encryptedBigInt = v3Authored(types.Bigint)
+export const encryptedBigIntEq = v3Authored(types.BigintEq)
+export const encryptedBigIntOrd = v3Authored(types.BigintOrd)
+// numeric
+export const encryptedNumeric = v3Authored(types.Numeric)
+export const encryptedNumericEq = v3Authored(types.NumericEq)
+export const encryptedNumericOrd = v3Authored(types.NumericOrd)
+// real
+export const encryptedReal = v3Authored(types.Real)
+export const encryptedRealEq = v3Authored(types.RealEq)
+export const encryptedRealOrd = v3Authored(types.RealOrd)
+// double
+export const encryptedDouble = v3Authored(types.Double)
+export const encryptedDoubleEq = v3Authored(types.DoubleEq)
+export const encryptedDoubleOrd = v3Authored(types.DoubleOrd)
+// date
+export const encryptedDate = v3Authored(types.Date)
+export const encryptedDateEq = v3Authored(types.DateEq)
+export const encryptedDateOrd = v3Authored(types.DateOrd)
+// timestamp
+export const encryptedTimestamp = v3Authored(types.Timestamp)
+export const encryptedTimestampEq = v3Authored(types.TimestampEq)
+export const encryptedTimestampOrd = v3Authored(types.TimestampOrd)
+// boolean (storage-only)
+export const encryptedBoolean = v3Authored(types.Boolean)
+// json (encrypted JSONB, ste_vec containment)
+export const encryptedJson = v3Authored(types.Json)
+
+// ---------------------------------------------------------------------------
+// v2 legacy aliases (verbatim pre-rename bodies, now named *V2)
+// ---------------------------------------------------------------------------
 
 /**
- * Search-mode parameters for `encryptedString({...})`. Every flag is
+ * Search-mode parameters for `encryptedStringV2({...})`. Every flag is
  * optional and defaults to `true` when omitted — searchable
  * encryption is the legitimate default. `orderAndRange` gives string
  * columns the same sortable / range-queryable surface the numeric +
@@ -53,16 +186,16 @@ export interface EncryptedStringColumnDescriptor {
 }
 
 /**
- * `encryptedString({ equality?, freeTextSearch?, orderAndRange? })` —
+ * `encryptedStringV2({ equality?, freeTextSearch?, orderAndRange? })` —
  * TS contract factory that lowers to a `ColumnTypeDescriptor` with
  * the `cipherstash/string@1` codec and the `eql_v2_encrypted`
  * Postgres native type. Each boolean flag becomes a `typeParams.*`
  * slot; all default to `true`.
  *
  * The shape matches what the PSL constructor
- * `cipherstash.EncryptedString({...})` lowers to, byte-for-byte.
+ * `cipherstash.EncryptedStringV2({...})` lowers to, byte-for-byte.
  */
-export function encryptedString(
+export function encryptedStringV2(
   options: EncryptedStringOptions = {},
 ): EncryptedStringColumnDescriptor {
   return {
@@ -77,8 +210,8 @@ export function encryptedString(
 }
 
 /**
- * Search-mode parameters for `encryptedDouble({...})` and
- * `encryptedBigInt({...})`. Both flags are optional and default to
+ * Search-mode parameters for `encryptedDoubleV2({...})` and
+ * `encryptedBigIntV2({...})`. Both flags are optional and default to
  * `true` when omitted — searchable encryption is the legitimate
  * default.
  */
@@ -106,13 +239,13 @@ export interface EncryptedBigIntColumnDescriptor {
 }
 
 /**
- * `encryptedDouble({ equality?, orderAndRange? })` — TS contract
+ * `encryptedDoubleV2({ equality?, orderAndRange? })` — TS contract
  * factory that lowers to a `ColumnTypeDescriptor` with the
  * `cipherstash/double@1` codec and the `eql_v2_encrypted` Postgres
  * native type. Mirrors what
- * `cipherstash.EncryptedDouble({...})` lowers to byte-for-byte.
+ * `cipherstash.EncryptedDoubleV2({...})` lowers to byte-for-byte.
  */
-export function encryptedDouble(
+export function encryptedDoubleV2(
   options: EncryptedNumericOptions = {},
 ): EncryptedDoubleColumnDescriptor {
   return {
@@ -126,10 +259,10 @@ export function encryptedDouble(
 }
 
 /**
- * `encryptedBigInt({ equality?, orderAndRange? })` — TS contract
- * factory matching `cipherstash.EncryptedBigInt({...})`.
+ * `encryptedBigIntV2({ equality?, orderAndRange? })` — TS contract
+ * factory matching `cipherstash.EncryptedBigIntV2({...})`.
  */
-export function encryptedBigInt(
+export function encryptedBigIntV2(
   options: EncryptedNumericOptions = {},
 ): EncryptedBigIntColumnDescriptor {
   return {
@@ -143,7 +276,7 @@ export function encryptedBigInt(
 }
 
 /**
- * Search-mode parameters for `encryptedDate({...})`. Both flags are
+ * Search-mode parameters for `encryptedDateV2({...})`. Both flags are
  * optional and default to `true`.
  */
 export interface EncryptedDateOptions {
@@ -161,10 +294,10 @@ export interface EncryptedDateColumnDescriptor {
 }
 
 /**
- * `encryptedDate({ equality?, orderAndRange? })` — TS contract factory
- * matching `cipherstash.EncryptedDate({...})`.
+ * `encryptedDateV2({ equality?, orderAndRange? })` — TS contract factory
+ * matching `cipherstash.EncryptedDateV2({...})`.
  */
-export function encryptedDate(
+export function encryptedDateV2(
   options: EncryptedDateOptions = {},
 ): EncryptedDateColumnDescriptor {
   return {
@@ -178,7 +311,7 @@ export function encryptedDate(
 }
 
 /**
- * Search-mode parameters for `encryptedBoolean({...})`. The flag is
+ * Search-mode parameters for `encryptedBooleanV2({...})`. The flag is
  * optional and defaults to `true`. Booleans only support equality
  * search (no meaningful range predicate over a 2-value domain).
  */
@@ -195,10 +328,10 @@ export interface EncryptedBooleanColumnDescriptor {
 }
 
 /**
- * `encryptedBoolean({ equality? })` — TS contract factory matching
- * `cipherstash.EncryptedBoolean({...})`.
+ * `encryptedBooleanV2({ equality? })` — TS contract factory matching
+ * `cipherstash.EncryptedBooleanV2({...})`.
  */
-export function encryptedBoolean(
+export function encryptedBooleanV2(
   options: EncryptedBooleanOptions = {},
 ): EncryptedBooleanColumnDescriptor {
   return {
@@ -211,7 +344,7 @@ export function encryptedBoolean(
 }
 
 /**
- * Search-mode parameters for `encryptedJson({...})`. Single flag —
+ * Search-mode parameters for `encryptedJsonV2({...})`. Single flag —
  * `searchableJson` gates the entire `ste_vec` index family (containment
  * + path-extraction predicates). Defaults to `true`.
  */
@@ -228,10 +361,10 @@ export interface EncryptedJsonColumnDescriptor {
 }
 
 /**
- * `encryptedJson({ searchableJson? })` — TS contract factory matching
- * `cipherstash.EncryptedJson({...})`.
+ * `encryptedJsonV2({ searchableJson? })` — TS contract factory matching
+ * `cipherstash.EncryptedJsonV2({...})`.
  */
-export function encryptedJson(
+export function encryptedJsonV2(
   options: EncryptedJsonOptions = {},
 ): EncryptedJsonColumnDescriptor {
   return {

packages/prisma-next/src/exports/column-types.ts

@@ -4,7 +4,10 @@
  * closed union derived from the imported catalog: `(codec id) ⟺ (public.*
  * domain)` is bijective, so the id set IS the catalog.
  */
-import type { AnyEncryptedV3Column, QueryCapabilities } from '@cipherstash/stack/eql/v3'
+import type {
+  AnyEncryptedV3Column,
+  QueryCapabilities,
+} from '@cipherstash/stack/eql/v3'
 import {
   CIPHERSTASH_TRAIT_EQUALITY,
   CIPHERSTASH_TRAIT_FREE_TEXT_SEARCH,
@@ -103,19 +106,28 @@ export const CIPHERSTASH_V3_CODEC_IDS = [
 // catalog gains a domain that is not pinned above, `Exclude<...>` is non-`never`
 // and this assignment fails to compile with the offending id in the error.
 type _PinnedId = (typeof CIPHERSTASH_V3_CODEC_IDS)[number]
-type _NoUnpinnedDomain = [Exclude<CipherstashV3CodecId, _PinnedId>] extends [never]
+type _NoUnpinnedDomain = [Exclude<CipherstashV3CodecId, _PinnedId>] extends [
+  never,
+]
   ? true
-  : ['catalog gained an unpinned codec id', Exclude<CipherstashV3CodecId, _PinnedId>]
+  : [
+      'catalog gained an unpinned codec id',
+      Exclude<CipherstashV3CodecId, _PinnedId>,
+    ]
 const _driftGuard: _NoUnpinnedDomain = true
 void _driftGuard
 
-export const CIPHERSTASH_V3_CODEC_ID_SET: ReadonlySet<string> = new Set(CIPHERSTASH_V3_CODEC_IDS)
+export const CIPHERSTASH_V3_CODEC_ID_SET: ReadonlySet<string> = new Set(
+  CIPHERSTASH_V3_CODEC_IDS,
+)
 
 export function isCipherstashV3CodecId(id: string): id is CipherstashV3CodecId {
   return CIPHERSTASH_V3_CODEC_ID_SET.has(id)
 }
 
-export function v3TraitsForCapabilities(caps: QueryCapabilities): readonly string[] {
+export function v3TraitsForCapabilities(
+  caps: QueryCapabilities,
+): readonly string[] {
   const traits: string[] = []
   if (caps.equality) traits.push(CIPHERSTASH_TRAIT_EQUALITY)
   if (caps.orderAndRange) traits.push(CIPHERSTASH_TRAIT_ORDER_AND_RANGE)
@@ -124,7 +136,8 @@ export function v3TraitsForCapabilities(caps: QueryCapabilities): readonly strin
   return traits
 }
 
-export const CIPHERSTASH_V3_BASELINE_MIGRATION_NAME = '20260601T0100_install_eql_v3_bundle'
+export const CIPHERSTASH_V3_BASELINE_MIGRATION_NAME =
+  '20260601T0100_install_eql_v3_bundle'
 
 export const CIPHERSTASH_V3_INVARIANTS = {
   installBundle: 'cipherstash:install-eql-v3-bundle-v1',