@prisma-next/extension-cipherstash 0.0.1

package/src/execution/operators.ts

@@ -0,0 +1,211 @@
+/**
+ * Cipherstash query-operations registry.
+ *
+ * `cipherstashEq` and `cipherstashIlike` lower to EQL's encrypted-aware
+ * comparison functions (`eql_v2.eq`, `eql_v2.ilike`) on
+ * `cipherstash/string@1`-typed columns. The lowering shape mirrors the
+ * canonical templates in the reference Prisma integration at
+ * `reference/cipherstash/stack/packages/stack/src/prisma/core/
+ * operation-templates.ts`:
+ *
+ *     eql_v2.eq(<self>, <encrypted-arg>)
+ *     eql_v2.ilike(<self>, <encrypted-arg>)
+ *
+ * Why we diverge from Postgres' native `=` / `ILIKE` operators: EQL
+ * ciphers contain randomized nonces, so two encrypts of the same
+ * plaintext do not byte-equal under SQL `=`. EQL's `eql_v2.eq` /
+ * `eql_v2.ilike` short-circuit through the per-column index
+ * (`unique` / `match`) emitted by the codec lifecycle hook and produce
+ * correct results.
+ *
+ * **Why cipherstash-namespaced method names (`cipherstashEq`,
+ * `cipherstashIlike`) rather than reusing the framework`s `eq` /
+ * `ilike`.** The framework`s `OperationRegistry` is a flat method-keyed
+ * map and operator overriding is disallowed by project decision. Equally
+ * importantly, cipherstash`s search operators are semantically distinct
+ * from the framework built-ins — they take encrypted-aware envelope
+ * arguments and lower to `eql_v2.eq` / `eql_v2.ilike`, which short-
+ * circuit through EQL`s per-column index — so they belong under a
+ * cipherstash-prefixed surface that flags the divergence at the call
+ * site. The supported user-facing call shape on a cipherstash column is:
+ *
+ *     model.users.where((u) => u.email.cipherstashEq('alice@example.com'))
+ *     model.users.where((u) => u.email.cipherstashIlike('%alice%'))
+ *
+ * The framework`s built-in `email.eq(...)` is **not reachable** on
+ * cipherstash columns: the cipherstash codec declares no `equality`
+ * trait (see `codec-runtime.ts` / `codec-metadata.ts` / `parameterized.ts`),
+ * and the model-accessor synthesis in `sql-orm-client` gates
+ * `COMPARISON_METHODS_META.eq` on the `equality` trait being present in
+ * the column codec`s trait set. Calling `email.eq(...)` on a cipherstash
+ * column is therefore `undefined` — the wrong-SQL footgun (where the
+ * built-in `eq` would lower to standard SQL `=` against an
+ * `eql_v2_encrypted` value, silently returning zero rows because EQL
+ * ciphers contain randomized nonces) is closed at the codec layer, not
+ * the operator layer. The trait declaration is regression-pinned by
+ * `test/equality-trait-removal.test.ts`.
+ *
+ * The encrypted-arg path: the operator wraps the user-supplied value
+ * in an `EncryptedString` envelope and stamps the column`s
+ * `(table, column)` routing context onto the envelope`s handle. The
+ * bulk-encrypt middleware then groups the envelope alongside
+ * any others targeting the same `(table, column)` and issues one
+ * `sdk.bulkEncrypt` per group. The cipherstash codec encodes the
+ * resulting ciphertext as the wire payload at
+ * `eql_v2_encrypted` cast time. Stamping at lowering time is the
+ * load-bearing step — the middleware`s AST walk only handles
+ * `InsertAst` / `UpdateAst` (see
+ * `src/middleware/bulk-encrypt.ts:stampRoutingKeysFromAst`); SELECT
+ * envelopes have to arrive at the middleware already routing-keyed.
+ *
+ * Build-time return type is the postgres `pg/bool@1` codec — that`s
+ * the codec the framework`s predicate machinery looks at via the
+ * `'boolean'` trait to decide that the operator`s return value is a
+ * predicate suitable for a WHERE clause (see
+ * `packages/3-extensions/sql-orm-client/src/model-accessor.ts:172-178`).
+ *
+ * **`isNull` / `isNotNull` are NOT registered here.** The framework`s
+ * always-on `isNull` / `isNotNull` comparison methods construct
+ * `NullCheckExpr` directly, bypassing
+ * the operator-registry dispatch, and lower to `<col> IS [NOT] NULL`
+ * regardless of codec — pinned by `test/operator-lowering.test.ts`.
+ */
+
+import type { SqlOperationDescriptor, SqlOperationDescriptors } from '@prisma-next/sql-operations';
+import { type AnyExpression, type ColumnRef, ParamRef } from '@prisma-next/sql-relational-core/ast';
+import {
+  buildOperation,
+  type Expression,
+  type ScopeField,
+  toExpr,
+} from '@prisma-next/sql-relational-core/expression';
+import { CIPHERSTASH_STRING_CODEC_ID } from '../extension-metadata/constants';
+import { EncryptedString, setHandleRoutingKey } from './envelope';
+
+/**
+ * Codec ID of the framework's Postgres boolean codec. Referenced as a
+ * string (rather than imported from `@prisma-next/target-postgres`)
+ * so cipherstash does not pick up a peer-dep on the target package
+ * just to identify a return-codec id. Mirrors the same pattern in the
+ * reference cipherstash integration's `operation-templates.ts:RETURN_BOOL`.
+ */
+const PG_BOOL_CODEC_ID = 'pg/bool@1' as const;
+
+type PgBoolReturn = { readonly codecId: typeof PG_BOOL_CODEC_ID; readonly nullable: false };
+
+/**
+ * Convert a user-supplied value (raw string plaintext or an existing
+ * `EncryptedString` envelope) into a `ParamRef` carrying an envelope
+ * tagged with the cipherstash storage codec id. The envelope's handle
+ * is stamped with the column's `(table, column)` routing context so
+ * the bulk-encrypt middleware can group it for SELECT-side bulk
+ * encryption (the middleware's AST walk only stamps for INSERT /
+ * UPDATE).
+ *
+ * Already-stamped envelopes are preserved write-once-wins per
+ * `setHandleRoutingKey`'s contract.
+ */
+function asEncryptedParam(selfAst: AnyExpression, value: unknown): ParamRef {
+  const envelope = coerceToEnvelope(value);
+  const columnRef = extractColumnRef(selfAst);
+  if (columnRef !== undefined) {
+    setHandleRoutingKey(envelope, columnRef.table, columnRef.column);
+  }
+  return ParamRef.of(envelope, { codecId: CIPHERSTASH_STRING_CODEC_ID });
+}
+
+function coerceToEnvelope(value: unknown): EncryptedString {
+  if (value instanceof EncryptedString) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    return EncryptedString.from(value);
+  }
+  throw new TypeError(
+    'cipherstash operator: expected a string plaintext or an EncryptedString envelope, ' +
+      `got ${value === null ? 'null' : typeof value}. ` +
+      'Use `EncryptedString.from(plaintext)` to construct an envelope explicitly, or ' +
+      'pass the plaintext directly and let the operator wrap it.',
+  );
+}
+
+/**
+ * Find the column reference inside a `self` expression so the operator
+ * can stamp its `(table, column)` onto the encrypted-param envelope.
+ *
+ * Most calls flow through the ORM model-accessor, where `self` is a
+ * column-field accessor whose `buildAst()` returns a `ColumnRef`
+ * directly. For more complex `self` expressions (e.g. wrapped in a
+ * function call) we fall back to the `baseColumnRef()` inherited from
+ * `Expression` — every standard AST node walks down to the underlying
+ * column. If no column is reachable (e.g. a literal `self`), routing
+ * stamping is skipped; the envelope will surface the
+ * "envelope reached the bulk-encrypt phase without a (table, column)
+ * routing context" diagnostic from `collectTargets` at execute time.
+ */
+function extractColumnRef(selfAst: AnyExpression): ColumnRef | undefined {
+  if (selfAst.kind === 'column-ref') {
+    return selfAst;
+  }
+  try {
+    return selfAst.baseColumnRef();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Build a cipherstash operator descriptor.
+ *
+ * @param publicMethod - The user-facing method name on the column
+ *   accessor (e.g. `cipherstashEq`). Must not collide with any
+ *   framework- or adapter-shipped method name.
+ * @param eqlFunction - The EQL function to lower to (`eq`, `ilike`).
+ *   Embedded into the SQL lowering template as `eql_v2.<eqlFunction>(...)`.
+ */
+function eqlOperator(publicMethod: string, eqlFunction: 'eq' | 'ilike'): SqlOperationDescriptor {
+  return {
+    self: { codecId: CIPHERSTASH_STRING_CODEC_ID },
+    impl: (self: Expression<ScopeField>, value: unknown): Expression<PgBoolReturn> => {
+      const selfAst = toExpr(self);
+      return buildOperation({
+        method: publicMethod,
+        args: [selfAst, asEncryptedParam(selfAst, value)],
+        returns: { codecId: PG_BOOL_CODEC_ID, nullable: false },
+        lowering: {
+          targetFamily: 'sql',
+          strategy: 'function',
+          template: `eql_v2.${eqlFunction}({{self}}, {{arg0}})`,
+        },
+      });
+    },
+  };
+}
+
+/**
+ * Cipherstash`s query-operations contributions. Wired into the
+ * runtime descriptor by `createCipherstashRuntimeDescriptor` and read
+ * by the SQL runtime`s `extractCodecLookup` / `queryOperations`
+ * aggregation (`packages/2-sql/5-runtime/src/sql-context.ts`). Two
+ * descriptors today:
+ *
+ *   - `cipherstashEq` — encrypted equality via EQL`s `unique` index.
+ *     SQL: `eql_v2.eq("col", $1::eql_v2_encrypted)`.
+ *   - `cipherstashIlike` — encrypted free-text match via EQL`s
+ *     `match` index. SQL:
+ *     `eql_v2.ilike("col", $1::eql_v2_encrypted)`.
+ *
+ * Both descriptors register `self: { codecId: 'cipherstash/string@1' }`
+ * so the model accessor only attaches them to columns whose codec id
+ * is exactly `cipherstash/string@1`. The method names are
+ * intentionally cipherstash-prefixed so they coexist with the
+ * framework`s `eq` / `ilike` registrations rather than overriding
+ * them — see the `Why unique method names` section in this file`s
+ * top-level docblock.
+ */
+export function cipherstashQueryOperations(): SqlOperationDescriptors {
+  return {
+    cipherstashEq: eqlOperator('cipherstashEq', 'eq'),
+    cipherstashIlike: eqlOperator('cipherstashIlike', 'ilike'),
+  };
+}

package/src/execution/parameterized.ts

@@ -0,0 +1,71 @@
+/**
+ * `RuntimeParameterizedCodecDescriptor` for the cipherstash storage
+ * codec — the post-#402 unified `CodecDescriptor<P>` shape consumed by
+ * the SQL runtime via `SqlStaticContributions.parameterizedCodecs()`.
+ *
+ * Mirrors pgvector's `vectorParamsSchema` + `vectorFactory` precedent
+ * (`packages/3-extensions/pgvector/src/exports/runtime.ts`). Cipherstash
+ * differs from pgvector in one respect: the codec depends on the SDK
+ * (read-side single-cell `decrypt`, the bulk-encrypt middleware), so
+ * each `createParameterizedCodecDescriptors(sdk)` call produces its
+ * own descriptor list closed over its SDK so multi-tenant
+ * deployments can side-by-side multiple cipherstash extensions without
+ * cross-talk.
+ *
+ * The factory is per-cell stateless across `(equality, freeTextSearch)`
+ * params on the write side (encode reads ciphertext from the handle,
+ * independent of the search-mode flags) — search-mode flags only affect
+ * operator lowering and the codec lifecycle hook on the control plane.
+ * The factory therefore returns the same shared codec
+ * for every params instance, mirroring pgvector's `vectorFactory`. When
+ * future per-instance state (e.g. decode-time index gating) lands, the
+ * closure is the place to add it.
+ */
+
+import type { CodecInstanceContext } from '@prisma-next/framework-components/codec';
+import type { RuntimeParameterizedCodecDescriptor } from '@prisma-next/sql-runtime';
+import { type as arktype } from 'arktype';
+import { CIPHERSTASH_STRING_CODEC_ID, createCipherstashStringCodec } from './codec-runtime';
+import type { CipherstashSdk } from './sdk';
+
+export interface CipherstashStringParams {
+  readonly equality: boolean;
+  readonly freeTextSearch: boolean;
+}
+
+export const encryptedStringParamsSchema = arktype({
+  equality: 'boolean',
+  freeTextSearch: 'boolean',
+});
+
+export function renderEncryptedStringOutputType(_params: CipherstashStringParams): string {
+  return 'EncryptedString';
+}
+
+export function createParameterizedCodecDescriptors(
+  sdk: CipherstashSdk,
+): ReadonlyArray<RuntimeParameterizedCodecDescriptor<CipherstashStringParams>> {
+  const sharedCodec = createCipherstashStringCodec(sdk);
+  const factory = (_params: CipherstashStringParams) => (_ctx: CodecInstanceContext) => sharedCodec;
+  return [
+    {
+      codecId: CIPHERSTASH_STRING_CODEC_ID,
+      // Empty traits — equality search on cipherstash columns goes
+      // through the cipherstash-namespaced operator (`cipherstashEq`
+      // in `./operators.ts`), not the framework`s trait-gated built-in
+      // `eq`. See `./codec-runtime.ts` for the full rationale.
+      traits: [] as const,
+      targetTypes: ['eql_v2_encrypted'] as const,
+      // Postgres native-type metadata. The SQL renderer reads this off
+      // the descriptor via `codecLookup.metaFor(codecId)` to insert the
+      // `$N::eql_v2_encrypted` cast on bound params (the EQL composite
+      // type isn`t inferrable from a `text` literal, so the cast is
+      // load-bearing).
+      meta: { db: { sql: { postgres: { nativeType: 'eql_v2_encrypted' } } } },
+      paramsSchema: encryptedStringParamsSchema,
+      isParameterized: true as const,
+      renderOutputType: renderEncryptedStringOutputType,
+      factory,
+    },
+  ] as const satisfies ReadonlyArray<RuntimeParameterizedCodecDescriptor<CipherstashStringParams>>;
+}

package/src/execution/routing.ts

@@ -0,0 +1,93 @@
+/**
+ * Routing-key derivation for cipherstash bulk operations.
+ *
+ * The routing key is derived from the envelope handle's
+ * `(table, column)` — there is no per-column override surface. Every
+ * cipherstash envelope passing through `bulkEncryptMiddleware` (and
+ * `decryptAll`) carries `(table, column)` on its handle, populated by
+ * the middleware's AST walk before the bulk-encrypt phase begins.
+ *
+ * `groupByRoutingKey` produces one homogeneous group per
+ * `(table, column)` pair so each `bulkEncrypt` call serves a single
+ * routing key — matching the SDK's
+ * `bulkEncrypt({ routingKey, values, signal })` shape. Heterogeneous
+ * batching is a future optimization.
+ */
+
+import type { EncryptedString } from './envelope';
+import type { CipherstashRoutingKey } from './sdk';
+
+/**
+ * Per-target context the bulk-encrypt middleware accumulates while
+ * walking `params.entries()`. Each target carries the envelope, its
+ * routing key (derived from the handle), the plaintext to encrypt, and
+ * the param-ref handle the mutator yielded so the post-encrypt
+ * `replaceValues` write-back can find the slot.
+ */
+export interface BulkEncryptTarget<TRef = unknown> {
+  readonly ref: TRef;
+  readonly plaintext: string;
+  readonly envelope: EncryptedString;
+  readonly routingKey: CipherstashRoutingKey;
+}
+
+/**
+ * Stable string key used to group targets by their `(table, column)`
+ * routing key. Exported for tests; not part of the package's public
+ * surface. Uses a NUL byte as the separator so the id never collides
+ * across pairs whose names happen to share a literal concatenation
+ * (e.g. `(a, bc)` vs `(ab, c)`).
+ */
+export function routingKeyId(routingKey: CipherstashRoutingKey): string {
+  return `${routingKey.table}\u0000${routingKey.column}`;
+}
+
+/**
+ * Read the routing key from an envelope's internal handle. Throws if
+ * the handle's `(table, column)` slots are unset — which happens when
+ * the bulk-encrypt middleware's AST walk did not see this envelope
+ * (typical cause: the envelope was passed in a context the AST walk
+ * does not yet handle, e.g. a raw-SQL plan with no `InsertAst` /
+ * `UpdateAst` arm). The throw matches the codec's
+ * "missing ciphertext" diagnostic shape: it points at the workflow that
+ * should have populated the slot.
+ */
+export function getRoutingKey(envelope: EncryptedString): CipherstashRoutingKey {
+  const handle = envelope.expose();
+  if (handle.table === undefined || handle.column === undefined) {
+    throw new Error(
+      'cipherstash bulk-encrypt: envelope has no (table, column) routing context. ' +
+        'The bulk-encrypt middleware stamps routing context from the lowered AST ' +
+        '(insert/update); raw-SQL plans embedding cipherstash envelopes must stamp ' +
+        'routing context explicitly before execute.',
+    );
+  }
+  return { table: handle.table, column: handle.column };
+}
+
+/**
+ * Group bulk-encrypt targets by `(table, column)` routing key. Each
+ * `Map` entry yields one homogeneous batch suitable for a single
+ * `sdk.bulkEncrypt({ routingKey, values, signal })` call.
+ *
+ * Order preservation: within each group, targets keep the order they
+ * were collected from `params.entries()` — which is the canonical
+ * ParamRef order the renderer's `$N` index map and the encode-side walk
+ * both consume. Iteration order across groups follows the order each
+ * routing key was first observed in the input.
+ */
+export function groupByRoutingKey<TRef>(
+  targets: ReadonlyArray<BulkEncryptTarget<TRef>>,
+): Map<string, BulkEncryptTarget<TRef>[]> {
+  const groups = new Map<string, BulkEncryptTarget<TRef>[]>();
+  for (const target of targets) {
+    const id = routingKeyId(target.routingKey);
+    let group = groups.get(id);
+    if (!group) {
+      group = [];
+      groups.set(id, group);
+    }
+    group.push(target);
+  }
+  return groups;
+}

package/src/execution/sdk.ts

@@ -0,0 +1,68 @@
+/**
+ * Framework-native shape for the CipherStash SDK that the cipherstash
+ * extension wraps.
+ *
+ * The first-attempt SDK (see `reference/cipherstash/stack/...`) is rich
+ * and Prisma-adapter shaped. The framework-native shape consumed by the
+ * codec runtime, the bulk-encrypt middleware, and `decryptAll` is
+ * intentionally smaller — three async methods that each map cleanly to
+ * one CipherStash bulk-call shape:
+ *
+ *   - `decrypt`     — single-cell read used by `EncryptedString#decrypt()`
+ *                     when the user opts out of bulk decryption.
+ *   - `bulkEncrypt` — write-side coalesced encrypt; the bulk-encrypt
+ *                     middleware calls this from `beforeExecute`.
+ *   - `bulkDecrypt` — read-side coalesced decrypt; `decryptAll` calls
+ *                     this from a recursive walker.
+ *
+ * Each method accepts an optional `AbortSignal`. Cancellation is forwarded
+ * directly to the SDK (the per-execute `MiddlewareContext.signal` from
+ * the middleware-param-transform seam, or the caller-supplied signal on
+ * `decrypt({signal})`).
+ */
+
+/**
+ * Routing-key tuple used by `bulkEncrypt`/`bulkDecrypt` to group requests
+ * so each ZeroKMS round-trip handles one homogeneous batch. Routing key
+ * is `(table, column)`.
+ */
+export interface CipherstashRoutingKey {
+  readonly table: string;
+  readonly column: string;
+}
+
+export interface CipherstashSingleDecryptArgs {
+  /**
+   * The wire ciphertext to decrypt. Opaque to the framework; the SDK
+   * inspects the embedded `i.t` / `i.c` schema markers to pick the
+   * right `cast_as` for the round-trip.
+   */
+  readonly ciphertext: unknown;
+  readonly table: string;
+  readonly column: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface CipherstashBulkEncryptArgs {
+  readonly routingKey: CipherstashRoutingKey;
+  readonly values: ReadonlyArray<string>;
+  readonly signal?: AbortSignal;
+}
+
+export interface CipherstashBulkDecryptArgs {
+  readonly routingKey: CipherstashRoutingKey;
+  readonly ciphertexts: ReadonlyArray<unknown>;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * The framework-native CipherStash SDK contract consumed by the envelope,
+ * codec, middleware, and `decryptAll` surfaces. Real implementations wrap
+ * a CipherStash `EncryptionClient`; tests construct mock SDKs that
+ * implement these three methods directly.
+ */
+export interface CipherstashSdk {
+  decrypt(args: CipherstashSingleDecryptArgs): Promise<string>;
+  bulkEncrypt(args: CipherstashBulkEncryptArgs): Promise<ReadonlyArray<unknown>>;
+  bulkDecrypt(args: CipherstashBulkDecryptArgs): Promise<ReadonlyArray<string>>;
+}

package/src/exports/column-types.ts

@@ -0,0 +1,62 @@
+/**
+ * TS contract factory for cipherstash-encrypted string columns.
+ *
+ * Counterpart to the PSL constructor `cipherstash.EncryptedString({...})`
+ * registered in `../contract/authoring.ts`. Both factories produce the same
+ * `ColumnTypeDescriptor` shape so PSL- and TS-authored contracts emit
+ * byte-identical `contract.json` (verified by the parity fixture under
+ * `test/integration/test/authoring/parity/cipherstash-encrypted-string/`).
+ *
+ * Both flags default 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 })`. Mirrors the PSL constructor's `true`
+ * defaults declared via `AuthoringArgRef.default`.
+ */
+
+import {
+  CIPHERSTASH_STRING_CODEC_ID,
+  EQL_V2_ENCRYPTED_TYPE,
+} from '../extension-metadata/constants';
+
+/**
+ * Search-mode parameters for `encryptedString({...})`. Both flags are
+ * optional and default to `true` when omitted.
+ */
+export interface EncryptedStringOptions {
+  readonly equality?: boolean;
+  readonly freeTextSearch?: boolean;
+}
+
+export interface EncryptedStringColumnDescriptor {
+  readonly codecId: typeof CIPHERSTASH_STRING_CODEC_ID;
+  readonly nativeType: typeof EQL_V2_ENCRYPTED_TYPE;
+  readonly typeParams: {
+    readonly equality: boolean;
+    readonly freeTextSearch: boolean;
+  };
+}
+
+/**
+ * `encryptedString({ equality?, freeTextSearch? })` — TS contract
+ * factory that lowers to a `ColumnTypeDescriptor` with the
+ * `cipherstash/string@1` codec and the `eql_v2_encrypted` Postgres
+ * native type. The two boolean flags become `typeParams.equality` and
+ * `typeParams.freeTextSearch`. Both default to `true`.
+ *
+ * The shape matches what the PSL constructor
+ * `cipherstash.EncryptedString({...})` lowers to, byte-for-byte.
+ */
+export function encryptedString(
+  options: EncryptedStringOptions = {},
+): EncryptedStringColumnDescriptor {
+  return {
+    codecId: CIPHERSTASH_STRING_CODEC_ID,
+    nativeType: EQL_V2_ENCRYPTED_TYPE,
+    typeParams: {
+      equality: options.equality ?? true,
+      freeTextSearch: options.freeTextSearch ?? true,
+    },
+  };
+}

package/src/exports/contract-space-typing.ts

@@ -0,0 +1,86 @@
+/**
+ * Typed-narrowing helpers for the on-disk contract-space JSON artefacts
+ * the cipherstash control descriptor wires into its
+ * `SqlControlExtensionDescriptor`.
+ *
+ * JSON-imported values come back as widened, structurally-typed
+ * objects: branded fields (`storageHash: StorageHashBase<string>`) and
+ * discriminated unions (`MigrationPlanOperation['operationClass']`)
+ * fall back to plain strings, so a direct assignment into the
+ * descriptor surfaces is a type error. The cipherstash MVP previously
+ * suppressed that error with `as unknown as X` triple-casts, which
+ * silently masks any future shape drift between the emitted JSON and
+ * the in-package descriptor.
+ *
+ * This module replaces the blind casts with thin runtime assertions
+ * that fail fast on drift and narrow the JSON inputs to the framework
+ * types in a single, auditable place. The assertions are intentionally
+ * minimal — they check the canonical discriminator fields (`storageHash`,
+ * `space`, `dirName`, `operationClass`, …) rather than re-validating
+ * the whole emitter contract — which is enough to surface schema-level
+ * drift while keeping the descriptor module light.
+ */
+
+import type { Contract } from '@prisma-next/contract/types';
+import type { MigrationPlanOperation } from '@prisma-next/framework-components/control';
+import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+
+function fail(field: string, value: unknown): never {
+  throw new Error(
+    `cipherstash contract-space JSON is missing or malformed at "${field}" (saw ${typeof value}). The on-disk JSON drifted from the framework's expected shape — re-run \`prisma-next contract emit\` and \`prisma-next migration plan\` for the cipherstash space.`,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Narrow a JSON-imported `contract.json` value to `Contract<SqlStorage>`.
+ * Checks the discriminators the framework relies on at descriptor
+ * registration time; everything else is consumed downstream by the
+ * runner / verifier, which performs its own validation.
+ */
+export function asCipherstashContract(value: unknown): Contract<SqlStorage> {
+  if (!isRecord(value)) fail('<root>', value);
+  if (typeof value['target'] !== 'string') fail('target', value['target']);
+  if (typeof value['targetFamily'] !== 'string') fail('targetFamily', value['targetFamily']);
+  const storage = value['storage'];
+  if (!isRecord(storage)) fail('storage', storage);
+  if (typeof storage['storageHash'] !== 'string')
+    fail('storage.storageHash', storage['storageHash']);
+  return value as unknown as Contract<SqlStorage>;
+}
+
+/**
+ * Narrow a JSON-imported `migration.json` value to `MigrationMetadata`.
+ * The framework's runner consumes the metadata for ordering /
+ * provenance; missing `to` or a non-string `migrationHash` here means
+ * a non-emitted artefact slipped into the import path.
+ */
+export function asCipherstashMigrationMetadata(value: unknown): MigrationMetadata {
+  if (!isRecord(value)) fail('<root>', value);
+  if (typeof value['to'] !== 'string') fail('to', value['to']);
+  if (typeof value['migrationHash'] !== 'string') fail('migrationHash', value['migrationHash']);
+  return value as unknown as MigrationMetadata;
+}
+
+/**
+ * Narrow a JSON-imported `ops.json` value to
+ * `readonly MigrationPlanOperation[]`. Checks each entry carries the
+ * canonical `id` / `operationClass` discriminator so a malformed entry
+ * doesn't reach the planner.
+ */
+export function asCipherstashMigrationOps(value: unknown): readonly MigrationPlanOperation[] {
+  if (!Array.isArray(value)) fail('<root>', value);
+  for (let index = 0; index < value.length; index += 1) {
+    const entry = value[index];
+    if (!isRecord(entry)) fail(`[${index}]`, entry);
+    if (typeof entry['id'] !== 'string') fail(`[${index}].id`, entry['id']);
+    if (typeof entry['operationClass'] !== 'string') {
+      fail(`[${index}].operationClass`, entry['operationClass']);
+    }
+  }
+  return value as unknown as readonly MigrationPlanOperation[];
+}