@cipherstash/stack 0.19.0 → 1.0.0-rc.1

package/dist/{types-public-CpS5KjwX.d.cts → types-public-QMjYNfQO.d.ts}

@@ -1,379 +1,40 @@
 import { JsPlaintext, EncryptedPayload, newClient, EncryptedQuery as EncryptedQuery$1, EncryptedV3Query, AuthStrategy, Encrypted as Encrypted$1 } from '@cipherstash/protect-ffi';
 import { z } from 'zod';
 
-/** Brand symbol for nominal typing */
-declare const __brand: unique symbol;
-/** Creates a branded type that is structurally incompatible with the base type */
-type Brand<T, B extends string> = T & {
-    readonly [__brand]: B;
-};
-type Client = Awaited<ReturnType<typeof newClient>> | undefined;
-/** A branded type representing encrypted data. Cannot be accidentally used as plaintext. */
-type EncryptedValue = Brand<Encrypted$1, 'encrypted'>;
-/** Structural type representing encrypted data stored in the database. Always
- * carries a ciphertext. Covers BOTH wire formats: the EQL v2.3 payloads
- * (`k: "ct"` / `k: "sv"`) and the EQL v3 payloads (flat `{v: 3, i, c, …}`
- * scalars and `{v: 3, k: "sv", i, sv}` SteVec documents). Which format
- * `encrypt` produces is selected by the client's
- * {@link ClientConfig.eqlVersion}; `decrypt` accepts both regardless.
- * v3 scalars carry no `k` discriminator, so narrow with `'k' in payload`
- * before reading it. See also `EncryptedValue` for branded nominal typing,
- * and {@link EncryptedQuery} for the search-term shape returned by
- * `encryptQuery`. */
-type Encrypted = EncryptedPayload;
-/** Structural type representing an encrypted query term (search needle)
- * returned by `encryptQuery` / `encryptQueryBulk` for scalar
- * (`unique` / `match` / `ore`) lookups and `ste_vec_selector` JSON path
- * queries, plus — under `eqlVersion: 3` — the `eql_v3.jsonb_query`
- * containment needle. Carries no ciphertext — matched against stored
- * values, never decrypted. v2 JSON containment queries (`ste_vec_term`)
- * return a storage-shaped {@link Encrypted} payload instead. */
-type EncryptedQuery = EncryptedQuery$1 | EncryptedV3Query;
 /**
- * Plaintext values the SDK accepts for encryption.
+ * Allowed cast types for CipherStash schema fields.
  *
- * Widens the FFI's `JsPlaintext` (`string | number | boolean |
- * Record<string, unknown> | JsPlaintext[]`) with `Date`. `Date` is a supported
- * cast target that is omitted from the FFI's `JsPlaintext` INPUT union, but it
- * serializes at the boundary via `toJSON` (ISO string), so it is accepted on the
- * way in.
+ * **Possible values:**
+ * - `"bigint"`
+ * - `"boolean"`
+ * - `"date"`
+ * - `"timestamp"`
+ * - `"number"`
+ * - `"string"`
+ * - `"json"`
+ * - `"text"`
  *
- * `bigint` is intentionally NOT included: the native `@cipherstash/protect-ffi`
- * build cannot marshal a JS `bigint` (V8 throws "Do not know how to serialize a
- * BigInt") and rejects a `string` for a `big_int` column. The v3 int8 domains
- * are therefore omitted from the SDK entirely (see `eql/v3`) until the FFI
- * supports lossless bigint I/O; `bigint` returns here alongside them.
+ * @remarks
+ * This is a Zod enum used at runtime to validate schema definitions.
+ * Use {@link CastAs} when typing your own code.
  *
- * When the upstream FFI `JsPlaintext` is corrected to include `Date`, the `Date`
- * arm can collapse back into `JsPlaintext`.
+ * @internal
  */
-type Plaintext = JsPlaintext | Date;
-type KeysetIdentifier = {
-    name: string;
-} | {
-    id: string;
-};
-type ClientConfig = {
-    /**
-     * The CipherStash workspace CRN (Cloud Resource Name).
-     * Format: `crn:<region>.aws:<workspace-id>`.
-     * Can also be set via the `CS_WORKSPACE_CRN` environment variable.
-     */
-    workspaceCrn?: string;
-    /**
-     * The API access key used for authenticating with the CipherStash API.
-     * Can also be set via the `CS_CLIENT_ACCESS_KEY` environment variable.
-     * Obtain this from the CipherStash dashboard after creating a workspace.
-     */
-    accessKey?: string;
-    /**
-     * The client identifier used to authenticate with CipherStash services.
-     * Can also be set via the `CS_CLIENT_ID` environment variable.
-     * Generated during workspace onboarding in the CipherStash dashboard.
-     */
-    clientId?: string;
-    /**
-     * The client key material used in combination with ZeroKMS for encryption operations.
-     * Can also be set via the `CS_CLIENT_KEY` environment variable.
-     * Generated during workspace onboarding in the CipherStash dashboard.
-     */
-    clientKey?: string;
-    /**
-     * An optional keyset identifier for multi-tenant encryption.
-     * Each keyset provides cryptographic isolation, giving each tenant its own keyspace.
-     * Specify by name (`{ name: "tenant-a" }`) or UUID (`{ id: "..." }`).
-     * Keysets are created and managed in the
-     * [dashboard](https://dashboard.cipherstash.com/workspaces/_/keysets); omit to
-     * use the workspace's default keyset. A client is bound to one keyset for its
-     * lifetime, so use one client per tenant.
-     *
-     * @see {@link Encryption} for the full keysets walkthrough.
-     */
-    keyset?: KeysetIdentifier;
-    /**
-     * An optional authentication strategy for ZeroKMS requests, from
-     * `@cipherstash/auth` (re-exported by `@cipherstash/stack`). When provided,
-     * its `getToken()` is invoked on every ZeroKMS request and takes precedence
-     * over the default `auto` strategy (the `clientKey` is still required for
-     * encryption). Use:
-     *
-     * - `OidcFederationStrategy` for per-user, identity-bound encryption —
-     *   federates an end user's OIDC JWT into a CTS service token, so requests
-     *   authenticate as that user. Pair with `.withLockContext({ identityClaim })`
-     *   to bind the data key to a claim. This replaces the older
-     *   `LockContext.identify()` ceremony.
-     * - `AccessKeyStrategy` for service-to-service / CI, or any custom
-     *   `{ getToken() }` object for bespoke token acquisition / caching.
-     *
-     * Leave unset to use the default `auto` strategy, which reads credentials
-     * from the `CS_*` environment variables and falls back to the local dev
-     * profile created by `npx stash auth login`.
-     *
-     * @see {@link AuthStrategy}
-     * @see {@link Encryption} for a full walkthrough of the authentication options.
-     */
-    authStrategy?: AuthStrategy;
-    /**
-     * @deprecated Renamed to {@link ClientConfig.authStrategy}. Still honoured for
-     * backwards compatibility — passing it logs a deprecation warning at runtime —
-     * but it will be removed in a future release. Set `authStrategy` instead.
-     */
-    strategy?: AuthStrategy;
-    /**
-     * The EQL wire version the client emits — one FFI client always emits
-     * exactly one wire format.
-     *
-     * - `2` (the protect-ffi default): payloads target the
-     *   `eql_v2_encrypted` column type.
-     * - `3`: payloads target the per-capability `eql_v3` domains
-     *   (`eql_v3.text_eq`, `eql_v3.integer_ord_ore`, `eql_v3.json`, …),
-     *   derived from each column's `cast_as` and indexes.
-     *
-     * When omitted, {@link Encryption} auto-detects from the schema set:
-     * EQL v3 tables (from `@cipherstash/stack/v3`, marked by
-     * `buildColumnKeyMap()`) select `3`; v2 tables leave the FFI default
-     * (`2`) untouched. Mixing v2 and v3 tables in one client is an error —
-     * split them across two clients instead.
-     *
-     * `decrypt` accepts BOTH formats regardless of this setting, so v2 and
-     * v3 data can coexist during a migration.
-     *
-     * v3 limitation (protect-ffi 0.27): `encryptQuery` supports only JSON
-     * containment queries — scalar-index and selector queries throw
-     * `EQL_V3_QUERY_UNSUPPORTED` until a v3 scalar query wire shape exists.
-     */
-    eqlVersion?: 2 | 3;
-};
-type AtLeastOneCsTable<T> = [T, ...T[]];
-/** Structural contract for a column builder the client can consume for STORAGE
- *  (`encrypt`). Satisfied by v2 `EncryptedColumn` / `EncryptedField` AND v3
- *  `EncryptedTextSearchColumn` — fields ARE encryptable, so this stays wide. */
-interface BuildableColumn {
-    getName(): string;
-    build(): ColumnSchema;
-}
-/** Structural contract for a column the client can consume for QUERIES
- *  (`encryptQuery` / search terms). Narrower than `BuildableColumn`: it must
- *  EXCLUDE non-queryable `EncryptedField` (a field has no indexes). A v2
- *  `EncryptedColumn` qualifies via the nominal arm; a v3 queryable concrete
- *  type qualifies via the `getEqlType()` structural arm; `EncryptedField` (no
- *  `getEqlType`, not an `EncryptedColumn`) is rejected. */
-interface BuildableV3QueryableColumn extends BuildableColumn {
-    getEqlType(): string;
-    getQueryCapabilities(): {
-        equality: boolean;
-        orderAndRange: boolean;
-        freeTextSearch: boolean;
-    };
-    isQueryable(): true;
-}
-type BuildableQueryColumn = EncryptedColumn | BuildableV3QueryableColumn;
-/** Structural contract for a table builder the client can consume. Satisfied by
- *  v2 and v3 `EncryptedTable` alike. */
-interface BuildableTable {
-    tableName: string;
-    build(): {
-        tableName: string;
-        columns: Record<string, ColumnSchema>;
-    };
-    /**
-     * Optional map from a model field's JS property name to its encrypt-config
-     * column name (the DB name). Present when the two can differ — v3 tables key
-     * their config by DB name (`column.getName()`) while models are written with
-     * JS property keys, so the model path must match by property but address the
-     * FFI/config by DB name.
-     *
-     * Absent on v2 tables, whose `build()` already keys columns by the JS property
-     * name; the model path then matches and addresses by that same key.
-     */
-    buildColumnKeyMap?(): Record<string, string>;
-}
-type EncryptionClientConfig = {
-    schemas: AtLeastOneCsTable<BuildableTable>;
-    config?: ClientConfig;
-};
 /**
- * The literal column map of a buildable table, read from its type-level
- * `_columnType` brand. Both v2 and v3 `EncryptedTable` carry this brand, so this
- * recovers the literal column keys structurally.
- *
- * This deliberately uses the `_columnType` brand rather than `build().columns`:
- * `BuildableTable.build()` is typed to return `Record<string, ColumnSchema>`,
- * which erases the literal keys and would mark EVERY model field as encrypted.
- *
- * The fallbacks resolve to `Record<never, never>` (a no-key type), NOT `never`:
- * a value typed as the bare structural `BuildableTable` carries no `_columnType`
- * brand, and `keyof never` is `string | number | symbol` — which would wrongly
- * mark EVERY model field as encrypted. `keyof Record<never, never>` is `never`,
- * so `EncryptedFromBuildableTable` degrades gracefully to the model unchanged.
+ * EQL cast types — the PostgreSQL-aligned types that EQL actually accepts.
+ * These are stored in the `cast_as` field of the EncryptConfig.
  */
-type BuildableTableColumns<T extends BuildableTable> = T extends {
-    readonly _columnType: infer C;
-} ? C extends Record<string, unknown> ? C : Record<never, never> : Record<never, never>;
+declare const eqlCastAsEnum: z.ZodDefault<z.ZodEnum<["text", "int", "small_int", "big_int", "real", "double", "boolean", "date", "timestamp", "jsonb"]>>;
 /**
- * Maps a plaintext model type to its encrypted form using a buildable table.
+ * SDK-facing data types — developer-friendly aliases accepted by `dataType()`.
  *
- * Fields whose keys match a column defined in `Table` (via its `_columnType`
- * brand) become `Encrypted` (`Encrypted | null` when the source field is
- * nullable); all other fields retain their original types from `T`. Works for
- * both v2 and v3 tables. See {@link EncryptedFromSchema} for the v2-specific
- * variant retained for backward compatibility.
- */
-type EncryptedFromBuildableTable<T, Table extends BuildableTable> = {
-    [K in keyof T]: [K] extends [keyof BuildableTableColumns<Table>] ? null extends T[K] ? Encrypted | null : Encrypted : T[K];
-};
-/**
- * Options for single-value encrypt operations.
- * Use a column from your table schema (from {@link encryptedColumn}) or a nested
- * field (from {@link encryptedField}) as the target for encryption.
+ * `timestamp` is distinct from `date`: `date` is calendar-date only (time-of-day
+ * truncated to midnight), while `timestamp` preserves the full date+time. v3
+ * `timestamp` domains set `cast_as: 'timestamp'` so the FFI keeps the instant.
  */
-type EncryptOptions = {
-    /** The column or nested field to encrypt into. From {@link EncryptedColumn} or {@link EncryptedField}. */
-    column: BuildableColumn;
-    table: BuildableTable;
-};
-/** Format for encrypted query/search term return values */
-type EncryptedReturnType = 'eql' | 'composite-literal' | 'escaped-composite-literal';
-type SearchTerm = {
-    value: Plaintext;
-    column: BuildableQueryColumn;
-    table: BuildableTable;
-    returnType?: EncryptedReturnType;
-};
-/** Encrypted search term result. `eql` return type yields either a storage
- * payload (`Encrypted`, for `ste_vec_term`) or a query-only term
- * (`EncryptedQuery`, for scalar lookups and `ste_vec_selector`); the
- * `composite-literal` return types yield a string. */
-type EncryptedSearchTerm = Encrypted | EncryptedQuery | string;
-/** Result of encryptQuery (single or batch). `eql` return type yields either a
- * storage payload (`Encrypted`) or a query-only term (`EncryptedQuery`); the
- * `composite-literal` return types yield a string. */
-type EncryptedQueryResult = Encrypted | EncryptedQuery | string | null;
-type EncryptedFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends Encrypted ? K : never]: T[K];
-};
-type OtherFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends Encrypted ? never : K]: T[K];
-};
-type DecryptedFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends Encrypted ? K : never]: null extends T[K] ? string | null : string;
-};
-/** Model with encrypted fields replaced by plaintext (decrypted) values */
-type Decrypted<T> = OtherFields<T> & DecryptedFields<T>;
+declare const castAsEnum: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "timestamp", "number", "string", "json", "text"]>>;
 /**
- * Maps a plaintext model type to its encrypted form using the table schema.
- *
- * Fields whose keys match columns defined in `S` become `Encrypted`;
- * all other fields retain their original types from `T`.
- *
- * When `S` is the widened `EncryptedTableColumn` (e.g. when a user passes an
- * explicit `<User>` type argument without specifying `S`), the type degrades
- * gracefully to `T` — preserving backward compatibility.
- *
- * @typeParam T - The plaintext model type (e.g. `{ id: string; email: string }`)
- * @typeParam S - The table schema column definition, inferred from the `table` argument
- *
- * @example
- * ```typescript
- * type User = { id: string; email: string }
- * // With a schema that defines `email`:
- * type Encrypted = EncryptedFromSchema<User, { email: EncryptedColumn }>
- * // => { id: string; email: Encrypted }
- * ```
- */
-type EncryptedFromSchema<T, S extends EncryptedTableColumn> = {
-    [K in keyof T]: [K] extends [keyof S] ? [S[K & keyof S]] extends [EncryptedColumn | EncryptedField] ? null extends T[K] ? Encrypted | null : Encrypted : T[K] : T[K];
-};
-type BulkEncryptPayload = Array<{
-    id?: string;
-    plaintext: Plaintext | null;
-}>;
-type BulkEncryptedData = Array<{
-    id?: string;
-    data: Encrypted | null;
-}>;
-type BulkDecryptPayload = Array<{
-    id?: string;
-    data: Encrypted | null;
-}>;
-type BulkDecryptedData = Array<DecryptionResult<JsPlaintext | null>>;
-type DecryptionSuccess<T> = {
-    error?: never;
-    data: T;
-    id?: string;
-};
-type DecryptionError<T> = {
-    error: T;
-    id?: string;
-    data?: never;
-};
-/**
- * Result type for individual items in bulk decrypt operations.
- * Uses `error`/`data` fields (not `failure`/`data`) since bulk operations
- * can have per-item failures.
- */
-type DecryptionResult<T> = DecryptionSuccess<T> | DecryptionError<T>;
-/**
- * User-facing query type names for encrypting query values.
- *
- * - `'equality'`: Exact match. [Exact Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)
- * - `'freeTextSearch'`: Text search. [Match Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)
- * - `'orderAndRange'`: Comparison and range. [Range Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)
- * - `'steVecSelector'`: JSONPath selector (e.g. `'$.user.email'`)
- * - `'steVecTerm'`: Containment (e.g. `{ role: 'admin' }`)
- * - `'searchableJson'`: Auto-infers selector or term from plaintext type (recommended)
- */
-type QueryTypeName = 'orderAndRange' | 'freeTextSearch' | 'equality' | 'steVecSelector' | 'steVecTerm' | 'searchableJson';
-declare const queryTypes: {
-    readonly orderAndRange: "orderAndRange";
-    readonly freeTextSearch: "freeTextSearch";
-    readonly equality: "equality";
-    readonly steVecSelector: "steVecSelector";
-    readonly steVecTerm: "steVecTerm";
-    readonly searchableJson: "searchableJson";
-};
-/** @internal */
-type QueryTermBase = {
-    column: BuildableQueryColumn;
-    table: BuildableTable;
-    queryType?: QueryTypeName;
-    returnType?: EncryptedReturnType;
-};
-type EncryptQueryOptions = QueryTermBase;
-type ScalarQueryTerm = QueryTermBase & {
-    value: Plaintext;
-};
-
-/**
- * Allowed cast types for CipherStash schema fields.
- *
- * **Possible values:**
- * - `"bigint"`
- * - `"boolean"`
- * - `"date"`
- * - `"timestamp"`
- * - `"number"`
- * - `"string"`
- * - `"json"`
- * - `"text"`
- *
- * @remarks
- * This is a Zod enum used at runtime to validate schema definitions.
- * Use {@link CastAs} when typing your own code.
- *
- * @internal
- */
-/**
- * EQL cast types — the PostgreSQL-aligned types that EQL actually accepts.
- * These are stored in the `cast_as` field of the EncryptConfig.
- */
-declare const eqlCastAsEnum: z.ZodDefault<z.ZodEnum<["text", "int", "small_int", "big_int", "real", "double", "boolean", "date", "timestamp", "jsonb"]>>;
-/**
- * SDK-facing data types — developer-friendly aliases accepted by `dataType()`.
- */
-declare const castAsEnum: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "timestamp", "number", "string", "json", "text"]>>;
-/**
- * Map SDK-facing data types to EQL `cast_as` values.
+ * Map SDK-facing data types to EQL `cast_as` values.
  *
  * The SDK accepts developer-friendly types like `'string'` and `'number'`,
  * but EQL expects PostgreSQL-aligned types like `'text'` and `'double'`.
@@ -387,6 +48,7 @@ declare const tokenFilterSchema: z.ZodObject<{
     kind: "downcase";
 }>;
 declare const oreIndexOptsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+declare const opeIndexOptsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 declare const uniqueIndexOptsSchema: z.ZodObject<{
     token_filters: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
         kind: z.ZodLiteral<"downcase">;
@@ -432,28 +94,28 @@ declare const matchIndexOptsSchema: z.ZodObject<{
     m: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
     include_original: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
-    token_filters?: {
-        kind: "downcase";
-    }[] | undefined;
     tokenizer?: {
         kind: "standard";
     } | {
         kind: "ngram";
         token_length: number;
     } | undefined;
+    token_filters?: {
+        kind: "downcase";
+    }[] | undefined;
     k?: number | undefined;
     m?: number | undefined;
     include_original?: boolean | undefined;
 }, {
-    token_filters?: {
-        kind: "downcase";
-    }[] | undefined;
     tokenizer?: {
         kind: "standard";
     } | {
         kind: "ngram";
         token_length: number;
     } | undefined;
+    token_filters?: {
+        kind: "downcase";
+    }[] | undefined;
     k?: number | undefined;
     m?: number | undefined;
     include_original?: boolean | undefined;
@@ -473,6 +135,7 @@ declare const steVecIndexOptsSchema: z.ZodObject<{
         wildcard?: boolean | undefined;
         position?: boolean | undefined;
     }>]>>;
+    mode: z.ZodOptional<z.ZodEnum<["compat", "standard"]>>;
 }, "strip", z.ZodTypeAny, {
     prefix: string;
     array_index_mode?: "all" | "none" | {
@@ -480,6 +143,7 @@ declare const steVecIndexOptsSchema: z.ZodObject<{
         wildcard?: boolean | undefined;
         position?: boolean | undefined;
     } | undefined;
+    mode?: "standard" | "compat" | undefined;
 }, {
     prefix: string;
     array_index_mode?: "all" | "none" | {
@@ -487,11 +151,13 @@ declare const steVecIndexOptsSchema: z.ZodObject<{
         wildcard?: boolean | undefined;
         position?: boolean | undefined;
     } | undefined;
+    mode?: "standard" | "compat" | undefined;
 }>;
 declare const columnSchema: z.ZodDefault<z.ZodObject<{
     cast_as: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "timestamp", "number", "string", "json", "text"]>>;
     indexes: z.ZodDefault<z.ZodObject<{
         ore: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+        ope: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
         unique: z.ZodOptional<z.ZodObject<{
             token_filters: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
                 kind: z.ZodLiteral<"downcase">;
@@ -537,28 +203,28 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
             m: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
             include_original: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
         }, "strip", z.ZodTypeAny, {
-            token_filters?: {
-                kind: "downcase";
-            }[] | undefined;
             tokenizer?: {
                 kind: "standard";
             } | {
                 kind: "ngram";
                 token_length: number;
             } | undefined;
+            token_filters?: {
+                kind: "downcase";
+            }[] | undefined;
             k?: number | undefined;
             m?: number | undefined;
             include_original?: boolean | undefined;
         }, {
-            token_filters?: {
-                kind: "downcase";
-            }[] | undefined;
             tokenizer?: {
                 kind: "standard";
             } | {
                 kind: "ngram";
                 token_length: number;
             } | undefined;
+            token_filters?: {
+                kind: "downcase";
+            }[] | undefined;
             k?: number | undefined;
             m?: number | undefined;
             include_original?: boolean | undefined;
@@ -578,6 +244,7 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
                 wildcard?: boolean | undefined;
                 position?: boolean | undefined;
             }>]>>;
+            mode: z.ZodOptional<z.ZodEnum<["compat", "standard"]>>;
         }, "strip", z.ZodTypeAny, {
             prefix: string;
             array_index_mode?: "all" | "none" | {
@@ -585,6 +252,7 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
                 wildcard?: boolean | undefined;
                 position?: boolean | undefined;
             } | undefined;
+            mode?: "standard" | "compat" | undefined;
         }, {
             prefix: string;
             array_index_mode?: "all" | "none" | {
@@ -592,27 +260,29 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
                 wildcard?: boolean | undefined;
                 position?: boolean | undefined;
             } | undefined;
+            mode?: "standard" | "compat" | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        match?: {
+        ore?: {} | undefined;
+        ope?: {} | undefined;
+        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+        } | undefined;
+        match?: {
             tokenizer?: {
                 kind: "standard";
             } | {
                 kind: "ngram";
                 token_length: number;
             } | undefined;
-            k?: number | undefined;
-            m?: number | undefined;
-            include_original?: boolean | undefined;
-        } | undefined;
-        ore?: {} | undefined;
-        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+            k?: number | undefined;
+            m?: number | undefined;
+            include_original?: boolean | undefined;
         } | undefined;
         ste_vec?: {
             prefix: string;
@@ -621,27 +291,29 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
                 wildcard?: boolean | undefined;
                 position?: boolean | undefined;
             } | undefined;
+            mode?: "standard" | "compat" | undefined;
         } | undefined;
     }, {
-        match?: {
+        ore?: {} | undefined;
+        ope?: {} | undefined;
+        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+        } | undefined;
+        match?: {
             tokenizer?: {
                 kind: "standard";
             } | {
                 kind: "ngram";
                 token_length: number;
             } | undefined;
-            k?: number | undefined;
-            m?: number | undefined;
-            include_original?: boolean | undefined;
-        } | undefined;
-        ore?: {} | undefined;
-        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+            k?: number | undefined;
+            m?: number | undefined;
+            include_original?: boolean | undefined;
         } | undefined;
         ste_vec?: {
             prefix: string;
@@ -650,30 +322,32 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
                 wildcard?: boolean | undefined;
                 position?: boolean | undefined;
             } | undefined;
+            mode?: "standard" | "compat" | undefined;
         } | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
+    cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json";
     indexes: {
-        match?: {
+        ore?: {} | undefined;
+        ope?: {} | undefined;
+        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+        } | undefined;
+        match?: {
             tokenizer?: {
                 kind: "standard";
             } | {
                 kind: "ngram";
                 token_length: number;
             } | undefined;
-            k?: number | undefined;
-            m?: number | undefined;
-            include_original?: boolean | undefined;
-        } | undefined;
-        ore?: {} | undefined;
-        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+            k?: number | undefined;
+            m?: number | undefined;
+            include_original?: boolean | undefined;
         } | undefined;
         ste_vec?: {
             prefix: string;
@@ -682,30 +356,32 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
                 wildcard?: boolean | undefined;
                 position?: boolean | undefined;
             } | undefined;
+            mode?: "standard" | "compat" | undefined;
         } | undefined;
     };
 }, {
-    cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text" | undefined;
+    cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json" | undefined;
     indexes?: {
-        match?: {
+        ore?: {} | undefined;
+        ope?: {} | undefined;
+        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+        } | undefined;
+        match?: {
             tokenizer?: {
                 kind: "standard";
             } | {
                 kind: "ngram";
                 token_length: number;
             } | undefined;
-            k?: number | undefined;
-            m?: number | undefined;
-            include_original?: boolean | undefined;
-        } | undefined;
-        ore?: {} | undefined;
-        unique?: {
             token_filters?: {
                 kind: "downcase";
             }[] | undefined;
+            k?: number | undefined;
+            m?: number | undefined;
+            include_original?: boolean | undefined;
         } | undefined;
         ste_vec?: {
             prefix: string;
@@ -714,6 +390,7 @@ declare const columnSchema: z.ZodDefault<z.ZodObject<{
                 wildcard?: boolean | undefined;
                 position?: boolean | undefined;
             } | undefined;
+            mode?: "standard" | "compat" | undefined;
         } | undefined;
     } | undefined;
 }>>;
@@ -724,6 +401,7 @@ declare const encryptConfigSchema: z.ZodObject<{
         cast_as: z.ZodDefault<z.ZodEnum<["bigint", "boolean", "date", "timestamp", "number", "string", "json", "text"]>>;
         indexes: z.ZodDefault<z.ZodObject<{
             ore: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
+            ope: z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>;
             unique: z.ZodOptional<z.ZodObject<{
                 token_filters: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodObject<{
                     kind: z.ZodLiteral<"downcase">;
@@ -769,28 +447,28 @@ declare const encryptConfigSchema: z.ZodObject<{
                 m: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
                 include_original: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
             }, "strip", z.ZodTypeAny, {
-                token_filters?: {
-                    kind: "downcase";
-                }[] | undefined;
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
+                token_filters?: {
+                    kind: "downcase";
+                }[] | undefined;
                 k?: number | undefined;
                 m?: number | undefined;
                 include_original?: boolean | undefined;
             }, {
-                token_filters?: {
-                    kind: "downcase";
-                }[] | undefined;
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
+                token_filters?: {
+                    kind: "downcase";
+                }[] | undefined;
                 k?: number | undefined;
                 m?: number | undefined;
                 include_original?: boolean | undefined;
@@ -810,6 +488,7 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 }>]>>;
+                mode: z.ZodOptional<z.ZodEnum<["compat", "standard"]>>;
             }, "strip", z.ZodTypeAny, {
                 prefix: string;
                 array_index_mode?: "all" | "none" | {
@@ -817,6 +496,7 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             }, {
                 prefix: string;
                 array_index_mode?: "all" | "none" | {
@@ -824,27 +504,29 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             }>>;
         }, "strip", z.ZodTypeAny, {
-            match?: {
+            ore?: {} | undefined;
+            ope?: {} | undefined;
+            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+            } | undefined;
+            match?: {
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
-                k?: number | undefined;
-                m?: number | undefined;
-                include_original?: boolean | undefined;
-            } | undefined;
-            ore?: {} | undefined;
-            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+                k?: number | undefined;
+                m?: number | undefined;
+                include_original?: boolean | undefined;
             } | undefined;
             ste_vec?: {
                 prefix: string;
@@ -853,27 +535,29 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             } | undefined;
         }, {
-            match?: {
+            ore?: {} | undefined;
+            ope?: {} | undefined;
+            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+            } | undefined;
+            match?: {
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
-                k?: number | undefined;
-                m?: number | undefined;
-                include_original?: boolean | undefined;
-            } | undefined;
-            ore?: {} | undefined;
-            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+                k?: number | undefined;
+                m?: number | undefined;
+                include_original?: boolean | undefined;
             } | undefined;
             ste_vec?: {
                 prefix: string;
@@ -882,30 +566,32 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             } | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json";
         indexes: {
-            match?: {
+            ore?: {} | undefined;
+            ope?: {} | undefined;
+            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+            } | undefined;
+            match?: {
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
-                k?: number | undefined;
-                m?: number | undefined;
-                include_original?: boolean | undefined;
-            } | undefined;
-            ore?: {} | undefined;
-            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+                k?: number | undefined;
+                m?: number | undefined;
+                include_original?: boolean | undefined;
             } | undefined;
             ste_vec?: {
                 prefix: string;
@@ -914,31 +600,33 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             } | undefined;
         };
     }, {
-        cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text" | undefined;
+        cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json" | undefined;
         indexes?: {
-            match?: {
+            ore?: {} | undefined;
+            ope?: {} | undefined;
+            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+            } | undefined;
+            match?: {
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
+                token_filters?: {
+                    kind: "downcase";
+                }[] | undefined;
                 k?: number | undefined;
                 m?: number | undefined;
                 include_original?: boolean | undefined;
             } | undefined;
-            ore?: {} | undefined;
-            unique?: {
-                token_filters?: {
-                    kind: "downcase";
-                }[] | undefined;
-            } | undefined;
             ste_vec?: {
                 prefix: string;
                 array_index_mode?: "all" | "none" | {
@@ -946,33 +634,35 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             } | undefined;
         } | undefined;
     }>>>>>>;
 }, "strip", z.ZodTypeAny, {
     v: number;
     tables: Record<string, Record<string, {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json";
         indexes: {
-            match?: {
+            ore?: {} | undefined;
+            ope?: {} | undefined;
+            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+            } | undefined;
+            match?: {
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
-                k?: number | undefined;
-                m?: number | undefined;
-                include_original?: boolean | undefined;
-            } | undefined;
-            ore?: {} | undefined;
-            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+                k?: number | undefined;
+                m?: number | undefined;
+                include_original?: boolean | undefined;
             } | undefined;
             ste_vec?: {
                 prefix: string;
@@ -981,33 +671,35 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             } | undefined;
         };
     }>>;
 }, {
     v: number;
     tables?: Record<string, Record<string, {
-        cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text" | undefined;
+        cast_as?: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json" | undefined;
         indexes?: {
-            match?: {
+            ore?: {} | undefined;
+            ope?: {} | undefined;
+            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+            } | undefined;
+            match?: {
                 tokenizer?: {
                     kind: "standard";
                 } | {
                     kind: "ngram";
                     token_length: number;
                 } | undefined;
-                k?: number | undefined;
-                m?: number | undefined;
-                include_original?: boolean | undefined;
-            } | undefined;
-            ore?: {} | undefined;
-            unique?: {
                 token_filters?: {
                     kind: "downcase";
                 }[] | undefined;
+                k?: number | undefined;
+                m?: number | undefined;
+                include_original?: boolean | undefined;
             } | undefined;
             ste_vec?: {
                 prefix: string;
@@ -1016,6 +708,7 @@ declare const encryptConfigSchema: z.ZodObject<{
                     wildcard?: boolean | undefined;
                     position?: boolean | undefined;
                 } | undefined;
+                mode?: "standard" | "compat" | undefined;
             } | undefined;
         } | undefined;
     } | undefined> | undefined> | undefined;
@@ -1033,6 +726,7 @@ type MatchIndexOpts = z.infer<typeof matchIndexOptsSchema>;
 type SteVecIndexOpts = z.infer<typeof steVecIndexOptsSchema>;
 type UniqueIndexOpts = z.infer<typeof uniqueIndexOptsSchema>;
 type OreIndexOpts = z.infer<typeof oreIndexOptsSchema>;
+type OpeIndexOpts = z.infer<typeof opeIndexOptsSchema>;
 type ColumnSchema = z.infer<typeof columnSchema>;
 /**
  * Shape of table columns: either top-level {@link EncryptedColumn} or nested
@@ -1053,323 +747,668 @@ type EncryptConfig = z.infer<typeof encryptConfigSchema>;
  * Create with {@link encryptedField}. Use inside nested objects in {@link encryptedTable};
  * supports `.dataType()` for plaintext type. No index methods (equality, orderAndRange, etc.).
  */
-declare class EncryptedField {
-    private valueName;
-    private castAsValue;
-    constructor(valueName: string);
+declare class EncryptedField {
+    private valueName;
+    private castAsValue;
+    constructor(valueName: string);
+    /**
+     * Set or override the plaintext data type for this field.
+     *
+     * By default all values are treated as `'string'`. Use this method to specify
+     * a different type so the encryption layer knows how to encode the plaintext
+     * before encrypting.
+     *
+     * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'timestamp'`, `'text'`, `'bigint'`, or `'json'`. Use `'timestamp'` (not `'date'`) to preserve time-of-day — `'date'` truncates to midnight.
+     * @returns This `EncryptedField` instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * import { encryptedField } from "@cipherstash/stack/schema"
+     *
+     * const age = encryptedField("age").dataType("number")
+     * ```
+     */
+    dataType(castAs: CastAs): this;
+    build(): {
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json";
+        indexes: {};
+    };
+    getName(): string;
+}
+declare class EncryptedColumn {
+    private columnName;
+    private castAsValue;
+    private indexesValue;
+    constructor(columnName: string);
+    /**
+     * Set or override the plaintext data type for this column.
+     *
+     * By default all columns are treated as `'string'`. Use this method to specify
+     * a different type so the encryption layer knows how to encode the plaintext
+     * before encrypting.
+     *
+     * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'timestamp'`, `'text'`, `'bigint'`, or `'json'`. Use `'timestamp'` (not `'date'`) to preserve time-of-day — `'date'` truncates to midnight.
+     * @returns This `EncryptedColumn` instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * import { encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * const dateOfBirth = encryptedColumn("date_of_birth").dataType("date")
+     * ```
+     */
+    dataType(castAs: CastAs): this;
+    /**
+     * Enable Order-Revealing Encryption (ORE) indexing on this column.
+     *
+     * ORE allows sorting, comparison, and range queries on encrypted data.
+     * Use with `encryptQuery` and `queryType: 'orderAndRange'`.
+     *
+     * @returns This `EncryptedColumn` instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * const users = encryptedTable("users", {
+     *   email: encryptedColumn("email").orderAndRange(),
+     * })
+     * ```
+     */
+    orderAndRange(): this;
+    /**
+     * Enable an exact-match (unique) index on this column.
+     *
+     * Allows equality queries on encrypted data. Use with `encryptQuery`
+     * and `queryType: 'equality'`.
+     *
+     * @param tokenFilters - Optional array of token filters (e.g. `[{ kind: 'downcase' }]`).
+     *   When omitted, no token filters are applied.
+     * @returns This `EncryptedColumn` instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * const users = encryptedTable("users", {
+     *   email: encryptedColumn("email").equality(),
+     * })
+     * ```
+     */
+    equality(tokenFilters?: TokenFilter[]): this;
+    /**
+     * Enable a full-text / fuzzy search (match) index on this column.
+     *
+     * Uses n-gram tokenization by default for substring and fuzzy matching.
+     * Use with `encryptQuery` and `queryType: 'freeTextSearch'`.
+     *
+     * @param opts - Optional match index configuration. Defaults to 3-character ngram
+     *   tokenization with a downcase filter, `k=6`, `m=2048`, and `include_original=true`.
+     * @returns This `EncryptedColumn` instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * const users = encryptedTable("users", {
+     *   email: encryptedColumn("email").freeTextSearch(),
+     * })
+     *
+     * // With custom options
+     * const posts = encryptedTable("posts", {
+     *   body: encryptedColumn("body").freeTextSearch({
+     *     tokenizer: { kind: "ngram", token_length: 4 },
+     *     k: 8,
+     *     m: 4096,
+     *   }),
+     * })
+     * ```
+     */
+    freeTextSearch(opts?: MatchIndexOpts): this;
+    /**
+     * Configure this column for searchable encrypted JSON (STE-Vec).
+     *
+     * Enables encrypted JSONPath selector queries (e.g. `'$.user.email'`) and
+     * containment queries (e.g. `{ role: 'admin' }`). Automatically sets the
+     * data type to `'json'`.
+     *
+     * When used with `encryptQuery`, the query operation is auto-inferred from
+     * the plaintext type: strings become selector queries, objects/arrays become
+     * containment queries.
+     *
+     * @returns This `EncryptedColumn` instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     *
+     * const documents = encryptedTable("documents", {
+     *   metadata: encryptedColumn("metadata").searchableJson(),
+     * })
+     * ```
+     */
+    searchableJson(): this;
+    build(): {
+        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "text" | "timestamp" | "json";
+        indexes: {
+            ore?: OreIndexOpts;
+            ope?: OpeIndexOpts;
+            unique?: UniqueIndexOpts;
+            match?: Required<MatchIndexOpts>;
+            ste_vec?: SteVecIndexOpts;
+        };
+    };
+    getName(): string;
+}
+interface TableDefinition {
+    tableName: string;
+    columns: Record<string, ColumnSchema>;
+}
+declare class EncryptedTable<T extends EncryptedTableColumn> {
+    readonly tableName: string;
+    readonly columnBuilders: T;
+    /** @internal Type-level brand so TypeScript can infer `T` from `EncryptedTable<T>`. */
+    readonly _columnType: T;
+    constructor(tableName: string, columnBuilders: T);
+    /**
+     * Compile this table schema into a `TableDefinition` used internally by the encryption client.
+     *
+     * Iterates over all column builders, calls `.build()` on each, and assembles
+     * the final `{ tableName, columns }` structure. For `searchableJson()` columns,
+     * the STE-Vec prefix is automatically set to `"<tableName>/<columnName>"`.
+     *
+     * @returns A `TableDefinition` containing the table name and built column configs.
+     *
+     * @example
+     * ```typescript
+     * const users = encryptedTable("users", {
+     *   email: encryptedColumn("email").equality(),
+     * })
+     *
+     * const definition = users.build()
+     * // { tableName: "users", columns: { email: { cast_as: "string", indexes: { unique: ... } } } }
+     * ```
+     */
+    build(): TableDefinition;
+}
+/**
+ * Infer the plaintext (decrypted) type from a EncryptedTable schema.
+ *
+ * @example
+ * ```typescript
+ * const users = encryptedTable("users", {
+ *   email: encryptedColumn("email").equality(),
+ *   name: encryptedColumn("name"),
+ * })
+ *
+ * type UserPlaintext = InferPlaintext<typeof users>
+ * // => { email: string; name: string }
+ * ```
+ */
+type InferPlaintext<T extends EncryptedTable<any>> = T extends EncryptedTable<infer C> ? {
+    [K in keyof C as C[K] extends EncryptedColumn | EncryptedField ? K : never]: string;
+} : never;
+/**
+ * Infer the encrypted type from a EncryptedTable schema.
+ *
+ * @example
+ * ```typescript
+ * const users = encryptedTable("users", {
+ *   email: encryptedColumn("email").equality(),
+ * })
+ *
+ * type UserEncrypted = InferEncrypted<typeof users>
+ * // => { email: Encrypted }
+ * ```
+ */
+type InferEncrypted<T extends EncryptedTable<any>> = T extends EncryptedTable<infer C> ? {
+    [K in keyof C as C[K] extends EncryptedColumn | EncryptedField ? K : never]: Encrypted;
+} : never;
+/**
+ * Define an encrypted table schema.
+ *
+ * Creates a `EncryptedTable` that maps a database table name to a set of encrypted
+ * column definitions. Pass the resulting object to `Encryption({ schemas: [...] })`
+ * when initializing the client.
+ *
+ * The returned object is also a proxy that exposes each column builder directly,
+ * so you can reference columns as `users.email` when calling `encrypt`, `decrypt`,
+ * and `encryptQuery`.
+ *
+ * @param tableName - The name of the database table this schema represents.
+ * @param columns - An object whose keys are logical column names and values are
+ *   {@link EncryptedColumn} from {@link encryptedColumn}, or nested objects whose
+ *   leaves are {@link EncryptedField} from {@link encryptedField}.
+ * @returns A `EncryptedTable<T> & T` that can be used as both a schema definition
+ *   and a column accessor.
+ *
+ * @example
+ * ```typescript
+ * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+ *
+ * const users = encryptedTable("users", {
+ *   email: encryptedColumn("email").equality().freeTextSearch(),
+ *   address: encryptedColumn("address"),
+ * })
+ *
+ * // Use as schema
+ * const client = await Encryption({ schemas: [users] })
+ *
+ * // Use as column accessor
+ * await client.encrypt("hello@example.com", { column: users.email, table: users })
+ * ```
+ */
+declare function encryptedTable<T extends EncryptedTableColumn>(tableName: string, columns: T): EncryptedTable<T> & T;
+/**
+ * Define an encrypted column within a table schema.
+ *
+ * Creates a `EncryptedColumn` builder for the given column name. Chain index
+ * methods (`.equality()`, `.freeTextSearch()`, `.orderAndRange()`,
+ * `.searchableJson()`) and/or `.dataType()` to configure searchable encryption
+ * and the plaintext data type.
+ *
+ * @param columnName - The name of the database column to encrypt.
+ * @returns A new `EncryptedColumn` builder.
+ *
+ * @example
+ * ```typescript
+ * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+ *
+ * const users = encryptedTable("users", {
+ *   email: encryptedColumn("email").equality().freeTextSearch().orderAndRange(),
+ * })
+ * ```
+ */
+declare function encryptedColumn(columnName: string): EncryptedColumn;
+/**
+ * Define an encrypted field for use in nested or structured schemas.
+ *
+ * `encryptedField` is similar to {@link encryptedColumn} but creates an {@link EncryptedField}
+ * for nested fields that are encrypted but not searchable (no indexes). Use `.dataType()`
+ * to specify the plaintext type.
+ *
+ * @param valueName - The name of the value field.
+ * @returns A new `EncryptedField` builder.
+ *
+ * @example
+ * ```typescript
+ * import { encryptedTable, encryptedField } from "@cipherstash/stack/schema"
+ *
+ * const orders = encryptedTable("orders", {
+ *   details: {
+ *     amount: encryptedField("amount").dataType("number"),
+ *     currency: encryptedField("currency"),
+ *   },
+ * })
+ * ```
+ */
+declare function encryptedField(valueName: string): EncryptedField;
+/**
+ * Build an encrypt config from a list of encrypted tables.
+ *
+ * @param protectTables - The list of encrypted tables to build the config from.
+ * @returns An encrypt config object.
+ *
+ * @example
+ * ```typescript
+ * import { buildEncryptConfig } from "@cipherstash/stack/schema"
+ *
+ * const users = encryptedTable("users", {
+ *   email: encryptedColumn("email").equality(),
+ * })
+ *
+ * const orders = encryptedTable("orders", {
+ *   amount: encryptedColumn("amount").dataType("number"),
+ * })
+ *
+ * const config = buildEncryptConfig(users, orders)
+ * console.log(config)
+ * ```
+ */
+declare function buildEncryptConfig(...protectTables: Array<BuildableTable>): EncryptConfig;
+
+/** Brand symbol for nominal typing */
+declare const __brand: unique symbol;
+/** Creates a branded type that is structurally incompatible with the base type */
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+type Client = Awaited<ReturnType<typeof newClient>> | undefined;
+/** A branded type representing encrypted data. Cannot be accidentally used as plaintext. */
+type EncryptedValue = Brand<Encrypted$1, 'encrypted'>;
+/** Structural type representing encrypted data stored in the database. Always
+ * carries a ciphertext. Covers BOTH wire formats: the EQL v2.3 payloads
+ * (`k: "ct"` / `k: "sv"`) and the EQL v3 payloads (flat `{v: 3, i, c, …}`
+ * scalars and `{v: 3, k: "sv", i, sv}` SteVec documents). Which format
+ * `encrypt` produces is selected by the client's
+ * {@link ClientConfig.eqlVersion}; `decrypt` accepts both regardless.
+ * v3 scalars carry no `k` discriminator, so narrow with `'k' in payload`
+ * before reading it. See also `EncryptedValue` for branded nominal typing,
+ * and {@link EncryptedQuery} for the search-term shape returned by
+ * `encryptQuery`. */
+type Encrypted = EncryptedPayload;
+/** Structural type representing an encrypted query term (search needle)
+ * returned by `encryptQuery` / `encryptQueryBulk` for scalar
+ * (`unique` / `match` / `ore`) lookups and `ste_vec_selector` JSON path
+ * queries, plus — under `eqlVersion: 3` — the `eql_v3.jsonb_query`
+ * containment needle. Carries no ciphertext — matched against stored
+ * values, never decrypted. v2 JSON containment queries (`ste_vec_term`)
+ * return a storage-shaped {@link Encrypted} payload instead. */
+type EncryptedQuery = EncryptedQuery$1 | EncryptedV3Query;
+/**
+ * Plaintext values the SDK accepts for encryption.
+ *
+ * Widens the FFI's `JsPlaintext` (`string | number | boolean |
+ * Record<string, unknown> | JsPlaintext[]`) with `Date` and `bigint`. `Date`
+ * is a supported cast target that is omitted from the FFI's `JsPlaintext` INPUT
+ * union, but it serializes at the boundary via `toJSON` (ISO string), so it is
+ * accepted on the way in.
+ *
+ * `bigint` is the plaintext for the v3 int8/bigint domains (see `eql/v3`),
+ * which always decrypt to a JS `bigint`. protect-ffi 0.28 marshals a native
+ * `bigint` across the Neon boundary losslessly. i64 bounds
+ * (`-2^63 … 2^63 - 1`) are enforced at the protect-ffi boundary, not here —
+ * out-of-range values surface as encryption errors from the FFI.
+ *
+ * When the upstream FFI `JsPlaintext` includes `Date` and `bigint`, both extra
+ * arms can collapse back into `JsPlaintext`.
+ */
+type Plaintext = JsPlaintext | Date | bigint;
+type KeysetIdentifier = {
+    name: string;
+} | {
+    id: string;
+};
+type ClientConfig = {
     /**
-     * Set or override the plaintext data type for this field.
-     *
-     * By default all values are treated as `'string'`. Use this method to specify
-     * a different type so the encryption layer knows how to encode the plaintext
-     * before encrypting.
-     *
-     * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'text'`, `'bigint'`, or `'json'`.
-     * @returns This `EncryptedField` instance for method chaining.
-     *
-     * @example
-     * ```typescript
-     * import { encryptedField } from "@cipherstash/stack/schema"
-     *
-     * const age = encryptedField("age").dataType("number")
-     * ```
+     * The CipherStash workspace CRN (Cloud Resource Name).
+     * Format: `crn:<region>.aws:<workspace-id>`.
+     * Can also be set via the `CS_WORKSPACE_CRN` environment variable.
      */
-    dataType(castAs: CastAs): this;
-    build(): {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
-        indexes: {};
-    };
-    getName(): string;
-}
-declare class EncryptedColumn {
-    private columnName;
-    private castAsValue;
-    private indexesValue;
-    constructor(columnName: string);
+    workspaceCrn?: string;
     /**
-     * Set or override the plaintext data type for this column.
-     *
-     * By default all columns are treated as `'string'`. Use this method to specify
-     * a different type so the encryption layer knows how to encode the plaintext
-     * before encrypting.
-     *
-     * @param castAs - The plaintext data type: `'string'`, `'number'`, `'boolean'`, `'date'`, `'bigint'`, or `'json'`.
-     * @returns This `EncryptedColumn` instance for method chaining.
-     *
-     * @example
-     * ```typescript
-     * import { encryptedColumn } from "@cipherstash/stack/schema"
-     *
-     * const dateOfBirth = encryptedColumn("date_of_birth").dataType("date")
-     * ```
+     * The API access key used for authenticating with the CipherStash API.
+     * Can also be set via the `CS_CLIENT_ACCESS_KEY` environment variable.
+     * Obtain this from the CipherStash dashboard after creating a workspace.
      */
-    dataType(castAs: CastAs): this;
+    accessKey?: string;
     /**
-     * Enable Order-Revealing Encryption (ORE) indexing on this column.
-     *
-     * ORE allows sorting, comparison, and range queries on encrypted data.
-     * Use with `encryptQuery` and `queryType: 'orderAndRange'`.
-     *
-     * @returns This `EncryptedColumn` instance for method chaining.
-     *
-     * @example
-     * ```typescript
-     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
-     *
-     * const users = encryptedTable("users", {
-     *   email: encryptedColumn("email").orderAndRange(),
-     * })
-     * ```
+     * The client identifier used to authenticate with CipherStash services.
+     * Can also be set via the `CS_CLIENT_ID` environment variable.
+     * Generated during workspace onboarding in the CipherStash dashboard.
      */
-    orderAndRange(): this;
+    clientId?: string;
     /**
-     * Enable an exact-match (unique) index on this column.
-     *
-     * Allows equality queries on encrypted data. Use with `encryptQuery`
-     * and `queryType: 'equality'`.
-     *
-     * @param tokenFilters - Optional array of token filters (e.g. `[{ kind: 'downcase' }]`).
-     *   When omitted, no token filters are applied.
-     * @returns This `EncryptedColumn` instance for method chaining.
-     *
-     * @example
-     * ```typescript
-     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
-     *
-     * const users = encryptedTable("users", {
-     *   email: encryptedColumn("email").equality(),
-     * })
-     * ```
+     * The client key material used in combination with ZeroKMS for encryption operations.
+     * Can also be set via the `CS_CLIENT_KEY` environment variable.
+     * Generated during workspace onboarding in the CipherStash dashboard.
      */
-    equality(tokenFilters?: TokenFilter[]): this;
+    clientKey?: string;
     /**
-     * Enable a full-text / fuzzy search (match) index on this column.
-     *
-     * Uses n-gram tokenization by default for substring and fuzzy matching.
-     * Use with `encryptQuery` and `queryType: 'freeTextSearch'`.
+     * An optional keyset identifier for multi-tenant encryption.
+     * Each keyset provides cryptographic isolation, giving each tenant its own keyspace.
+     * Specify by name (`{ name: "tenant-a" }`) or UUID (`{ id: "..." }`).
+     * Keysets are created and managed in the
+     * [dashboard](https://dashboard.cipherstash.com/workspaces/_/keysets); omit to
+     * use the workspace's default keyset. A client is bound to one keyset for its
+     * lifetime, so use one client per tenant.
      *
-     * @param opts - Optional match index configuration. Defaults to 3-character ngram
-     *   tokenization with a downcase filter, `k=6`, `m=2048`, and `include_original=true`.
-     * @returns This `EncryptedColumn` instance for method chaining.
+     * @see {@link Encryption} for the full keysets walkthrough.
+     */
+    keyset?: KeysetIdentifier;
+    /**
+     * An optional authentication strategy for ZeroKMS requests, from
+     * `@cipherstash/auth` (re-exported by `@cipherstash/stack`). When provided,
+     * its `getToken()` is invoked on every ZeroKMS request and takes precedence
+     * over the default `auto` strategy (the `clientKey` is still required for
+     * encryption). Use:
      *
-     * @example
-     * ```typescript
-     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     * - `OidcFederationStrategy` for per-user, identity-bound encryption —
+     *   federates an end user's OIDC JWT into a CTS service token, so requests
+     *   authenticate as that user. Pair with `.withLockContext({ identityClaim })`
+     *   to bind the data key to a claim. This replaces the older
+     *   `LockContext.identify()` ceremony.
+     * - `AccessKeyStrategy` for service-to-service / CI, or any custom
+     *   `{ getToken() }` object for bespoke token acquisition / caching.
      *
-     * const users = encryptedTable("users", {
-     *   email: encryptedColumn("email").freeTextSearch(),
-     * })
+     * Leave unset to use the default `auto` strategy, which reads credentials
+     * from the `CS_*` environment variables and falls back to the local dev
+     * profile created by `npx stash auth login`.
      *
-     * // With custom options
-     * const posts = encryptedTable("posts", {
-     *   body: encryptedColumn("body").freeTextSearch({
-     *     tokenizer: { kind: "ngram", token_length: 4 },
-     *     k: 8,
-     *     m: 4096,
-     *   }),
-     * })
-     * ```
+     * @see {@link AuthStrategy}
+     * @see {@link Encryption} for a full walkthrough of the authentication options.
      */
-    freeTextSearch(opts?: MatchIndexOpts): this;
+    authStrategy?: AuthStrategy;
     /**
-     * Configure this column for searchable encrypted JSON (STE-Vec).
-     *
-     * Enables encrypted JSONPath selector queries (e.g. `'$.user.email'`) and
-     * containment queries (e.g. `{ role: 'admin' }`). Automatically sets the
-     * data type to `'json'`.
+     * @deprecated Renamed to {@link ClientConfig.authStrategy}. Still honoured for
+     * backwards compatibility — passing it logs a deprecation warning at runtime —
+     * but it will be removed in a future release. Set `authStrategy` instead.
+     */
+    strategy?: AuthStrategy;
+    /**
+     * The EQL wire version the client emits — one FFI client always emits
+     * exactly one wire format.
      *
-     * When used with `encryptQuery`, the query operation is auto-inferred from
-     * the plaintext type: strings become selector queries, objects/arrays become
-     * containment queries.
+     * - `2` (the protect-ffi default): payloads target the
+     *   `eql_v2_encrypted` column type.
+     * - `3`: payloads target the per-capability `eql_v3` domains
+     *   (`eql_v3.text_eq`, `eql_v3.integer_ord_ore`, `eql_v3.json`, …),
+     *   derived from each column's `cast_as` and indexes.
      *
-     * @returns This `EncryptedColumn` instance for method chaining.
+     * When omitted, {@link Encryption} auto-detects from the schema set:
+     * EQL v3 tables (from `@cipherstash/stack/v3`, marked by
+     * `buildColumnKeyMap()`) select `3`; v2 tables leave the FFI default
+     * (`2`) untouched. Mixing v2 and v3 tables in one client is an error —
+     * split them across two clients instead.
      *
-     * @example
-     * ```typescript
-     * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
+     * `decrypt` accepts BOTH formats regardless of this setting, so v2 and
+     * v3 data can coexist during a migration.
      *
-     * const documents = encryptedTable("documents", {
-     *   metadata: encryptedColumn("metadata").searchableJson(),
-     * })
-     * ```
+     * Under `3`, `encryptQuery` returns EQL v3 query operands (protect-ffi
+     * 0.29+): term-only scalar operands for the `eql_v3.query_<name>` twins,
+     * the `eql_v3.query_jsonb` containment needle, and bare selector-hash
+     * strings for JSON path queries.
      */
-    searchableJson(): this;
-    build(): {
-        cast_as: "string" | "number" | "bigint" | "boolean" | "date" | "timestamp" | "json" | "text";
-        indexes: {
-            ore?: OreIndexOpts;
-            unique?: UniqueIndexOpts;
-            match?: Required<MatchIndexOpts>;
-            ste_vec?: SteVecIndexOpts;
-        };
-    };
+    eqlVersion?: 2 | 3;
+};
+type AtLeastOneCsTable<T> = [T, ...T[]];
+/** Structural contract for a column builder the client can consume for STORAGE
+ *  (`encrypt`). Satisfied by v2 `EncryptedColumn` / `EncryptedField` AND v3
+ *  `EncryptedTextSearchColumn` — fields ARE encryptable, so this stays wide. */
+interface BuildableColumn {
     getName(): string;
+    build(): ColumnSchema;
 }
-interface TableDefinition {
-    tableName: string;
-    columns: Record<string, ColumnSchema>;
+/** Structural contract for a column the client can consume for QUERIES
+ *  (`encryptQuery` / search terms). Narrower than `BuildableColumn`: it must
+ *  EXCLUDE non-queryable `EncryptedField` (a field has no indexes). A v2
+ *  `EncryptedColumn` qualifies via the nominal arm; a v3 queryable concrete
+ *  type qualifies via the `getEqlType()` structural arm; `EncryptedField` (no
+ *  `getEqlType`, not an `EncryptedColumn`) is rejected. */
+interface BuildableV3QueryableColumn extends BuildableColumn {
+    getEqlType(): string;
+    getQueryCapabilities(): {
+        equality: boolean;
+        orderAndRange: boolean;
+        freeTextSearch: boolean;
+    };
+    isQueryable(): true;
 }
-declare class EncryptedTable<T extends EncryptedTableColumn> {
-    readonly tableName: string;
-    readonly columnBuilders: T;
-    /** @internal Type-level brand so TypeScript can infer `T` from `EncryptedTable<T>`. */
-    readonly _columnType: T;
-    constructor(tableName: string, columnBuilders: T);
+type BuildableQueryColumn = EncryptedColumn | BuildableV3QueryableColumn;
+/** Structural contract for a table builder the client can consume. Satisfied by
+ *  v2 and v3 `EncryptedTable` alike. */
+interface BuildableTable {
+    tableName: string;
+    build(): {
+        tableName: string;
+        columns: Record<string, ColumnSchema>;
+    };
     /**
-     * Compile this table schema into a `TableDefinition` used internally by the encryption client.
-     *
-     * Iterates over all column builders, calls `.build()` on each, and assembles
-     * the final `{ tableName, columns }` structure. For `searchableJson()` columns,
-     * the STE-Vec prefix is automatically set to `"<tableName>/<columnName>"`.
-     *
-     * @returns A `TableDefinition` containing the table name and built column configs.
-     *
-     * @example
-     * ```typescript
-     * const users = encryptedTable("users", {
-     *   email: encryptedColumn("email").equality(),
-     * })
+     * Optional map from a model field's JS property name to its encrypt-config
+     * column name (the DB name). Present when the two can differ — v3 tables key
+     * their config by DB name (`column.getName()`) while models are written with
+     * JS property keys, so the model path must match by property but address the
+     * FFI/config by DB name.
      *
-     * const definition = users.build()
-     * // { tableName: "users", columns: { email: { cast_as: "string", indexes: { unique: ... } } } }
-     * ```
+     * Absent on v2 tables, whose `build()` already keys columns by the JS property
+     * name; the model path then matches and addresses by that same key.
      */
-    build(): TableDefinition;
+    buildColumnKeyMap?(): Record<string, string>;
 }
+type EncryptionClientConfig = {
+    schemas: AtLeastOneCsTable<BuildableTable>;
+    config?: ClientConfig;
+};
 /**
- * Infer the plaintext (decrypted) type from a EncryptedTable schema.
+ * The literal column map of a buildable table, read from its type-level
+ * `_columnType` brand. Both v2 and v3 `EncryptedTable` carry this brand, so this
+ * recovers the literal column keys structurally.
  *
- * @example
- * ```typescript
- * const users = encryptedTable("users", {
- *   email: encryptedColumn("email").equality(),
- *   name: encryptedColumn("name"),
- * })
+ * This deliberately uses the `_columnType` brand rather than `build().columns`:
+ * `BuildableTable.build()` is typed to return `Record<string, ColumnSchema>`,
+ * which erases the literal keys and would mark EVERY model field as encrypted.
  *
- * type UserPlaintext = InferPlaintext<typeof users>
- * // => { email: string; name: string }
- * ```
+ * The fallbacks resolve to `Record<never, never>` (a no-key type), NOT `never`:
+ * a value typed as the bare structural `BuildableTable` carries no `_columnType`
+ * brand, and `keyof never` is `string | number | symbol` — which would wrongly
+ * mark EVERY model field as encrypted. `keyof Record<never, never>` is `never`,
+ * so `EncryptedFromBuildableTable` degrades gracefully to the model unchanged.
  */
-type InferPlaintext<T extends EncryptedTable<any>> = T extends EncryptedTable<infer C> ? {
-    [K in keyof C as C[K] extends EncryptedColumn | EncryptedField ? K : never]: string;
-} : never;
+type BuildableTableColumns<T extends BuildableTable> = T extends {
+    readonly _columnType: infer C;
+} ? C extends Record<string, unknown> ? C : Record<never, never> : Record<never, never>;
 /**
- * Infer the encrypted type from a EncryptedTable schema.
- *
- * @example
- * ```typescript
- * const users = encryptedTable("users", {
- *   email: encryptedColumn("email").equality(),
- * })
+ * Maps a plaintext model type to its encrypted form using a buildable table.
  *
- * type UserEncrypted = InferEncrypted<typeof users>
- * // => { email: Encrypted }
- * ```
+ * Fields whose keys match a column defined in `Table` (via its `_columnType`
+ * brand) become `Encrypted` (`Encrypted | null` when the source field is
+ * nullable); all other fields retain their original types from `T`. Works for
+ * both v2 and v3 tables. See {@link EncryptedFromSchema} for the v2-specific
+ * variant retained for backward compatibility.
  */
-type InferEncrypted<T extends EncryptedTable<any>> = T extends EncryptedTable<infer C> ? {
-    [K in keyof C as C[K] extends EncryptedColumn | EncryptedField ? K : never]: Encrypted;
-} : never;
+type EncryptedFromBuildableTable<T, Table extends BuildableTable> = {
+    [K in keyof T]: [K] extends [keyof BuildableTableColumns<Table>] ? null extends T[K] ? Encrypted | null : Encrypted : T[K];
+};
 /**
- * Define an encrypted table schema.
- *
- * Creates a `EncryptedTable` that maps a database table name to a set of encrypted
- * column definitions. Pass the resulting object to `Encryption({ schemas: [...] })`
- * when initializing the client.
- *
- * The returned object is also a proxy that exposes each column builder directly,
- * so you can reference columns as `users.email` when calling `encrypt`, `decrypt`,
- * and `encryptQuery`.
- *
- * @param tableName - The name of the database table this schema represents.
- * @param columns - An object whose keys are logical column names and values are
- *   {@link EncryptedColumn} from {@link encryptedColumn}, or nested objects whose
- *   leaves are {@link EncryptedField} from {@link encryptedField}.
- * @returns A `EncryptedTable<T> & T` that can be used as both a schema definition
- *   and a column accessor.
- *
- * @example
- * ```typescript
- * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
- *
- * const users = encryptedTable("users", {
- *   email: encryptedColumn("email").equality().freeTextSearch(),
- *   address: encryptedColumn("address"),
- * })
- *
- * // Use as schema
- * const client = await Encryption({ schemas: [users] })
- *
- * // Use as column accessor
- * await client.encrypt("hello@example.com", { column: users.email, table: users })
- * ```
+ * Options for single-value encrypt operations.
+ * Use a column from your table schema (from {@link encryptedColumn}) or a nested
+ * field (from {@link encryptedField}) as the target for encryption.
  */
-declare function encryptedTable<T extends EncryptedTableColumn>(tableName: string, columns: T): EncryptedTable<T> & T;
+type EncryptOptions = {
+    /** The column or nested field to encrypt into. From {@link EncryptedColumn} or {@link EncryptedField}. */
+    column: BuildableColumn;
+    table: BuildableTable;
+};
+/** Format for encrypted query/search term return values */
+type EncryptedReturnType = 'eql' | 'composite-literal' | 'escaped-composite-literal';
+type SearchTerm = {
+    value: Plaintext;
+    column: BuildableQueryColumn;
+    table: BuildableTable;
+    returnType?: EncryptedReturnType;
+};
+/** Encrypted search term result. `eql` return type yields either a storage
+ * payload (`Encrypted`, for `ste_vec_term`) or a query-only term
+ * (`EncryptedQuery`, for scalar lookups and `ste_vec_selector`); the
+ * `composite-literal` return types yield a string. */
+type EncryptedSearchTerm = Encrypted | EncryptedQuery | string;
+/** Result of encryptQuery (single or batch). `eql` return type yields either a
+ * storage payload (`Encrypted`) or a query-only term (`EncryptedQuery`); the
+ * `composite-literal` return types yield a string. */
+type EncryptedQueryResult = Encrypted | EncryptedQuery | string | null;
+type EncryptedFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends Encrypted ? K : never]: T[K];
+};
+type OtherFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends Encrypted ? never : K]: T[K];
+};
+type DecryptedFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends Encrypted ? K : never]: null extends T[K] ? string | null : string;
+};
+/** Model with encrypted fields replaced by plaintext (decrypted) values */
+type Decrypted<T> = OtherFields<T> & DecryptedFields<T>;
 /**
- * Define an encrypted column within a table schema.
+ * Maps a plaintext model type to its encrypted form using the table schema.
  *
- * Creates a `EncryptedColumn` builder for the given column name. Chain index
- * methods (`.equality()`, `.freeTextSearch()`, `.orderAndRange()`,
- * `.searchableJson()`) and/or `.dataType()` to configure searchable encryption
- * and the plaintext data type.
+ * Fields whose keys match columns defined in `S` become `Encrypted`;
+ * all other fields retain their original types from `T`.
  *
- * @param columnName - The name of the database column to encrypt.
- * @returns A new `EncryptedColumn` builder.
+ * When `S` is the widened `EncryptedTableColumn` (e.g. when a user passes an
+ * explicit `<User>` type argument without specifying `S`), the type degrades
+ * gracefully to `T` — preserving backward compatibility.
+ *
+ * @typeParam T - The plaintext model type (e.g. `{ id: string; email: string }`)
+ * @typeParam S - The table schema column definition, inferred from the `table` argument
  *
  * @example
  * ```typescript
- * import { encryptedTable, encryptedColumn } from "@cipherstash/stack/schema"
- *
- * const users = encryptedTable("users", {
- *   email: encryptedColumn("email").equality().freeTextSearch().orderAndRange(),
- * })
+ * type User = { id: string; email: string }
+ * // With a schema that defines `email`:
+ * type Encrypted = EncryptedFromSchema<User, { email: EncryptedColumn }>
+ * // => { id: string; email: Encrypted }
  * ```
  */
-declare function encryptedColumn(columnName: string): EncryptedColumn;
+type EncryptedFromSchema<T, S extends EncryptedTableColumn> = {
+    [K in keyof T]: [K] extends [keyof S] ? [S[K & keyof S]] extends [EncryptedColumn | EncryptedField] ? null extends T[K] ? Encrypted | null : Encrypted : T[K] : T[K];
+};
+type BulkEncryptPayload = Array<{
+    id?: string;
+    plaintext: Plaintext | null;
+}>;
+type BulkEncryptedData = Array<{
+    id?: string;
+    data: Encrypted | null;
+}>;
+type BulkDecryptPayload = Array<{
+    id?: string;
+    data: Encrypted | null;
+}>;
+type BulkDecryptedData = Array<DecryptionResult<JsPlaintext | null>>;
+type DecryptionSuccess<T> = {
+    error?: never;
+    data: T;
+    id?: string;
+};
+type DecryptionError<T> = {
+    error: T;
+    id?: string;
+    data?: never;
+};
 /**
- * Define an encrypted field for use in nested or structured schemas.
- *
- * `encryptedField` is similar to {@link encryptedColumn} but creates an {@link EncryptedField}
- * for nested fields that are encrypted but not searchable (no indexes). Use `.dataType()`
- * to specify the plaintext type.
- *
- * @param valueName - The name of the value field.
- * @returns A new `EncryptedField` builder.
- *
- * @example
- * ```typescript
- * import { encryptedTable, encryptedField } from "@cipherstash/stack/schema"
- *
- * const orders = encryptedTable("orders", {
- *   details: {
- *     amount: encryptedField("amount").dataType("number"),
- *     currency: encryptedField("currency"),
- *   },
- * })
- * ```
+ * Result type for individual items in bulk decrypt operations.
+ * Uses `error`/`data` fields (not `failure`/`data`) since bulk operations
+ * can have per-item failures.
  */
-declare function encryptedField(valueName: string): EncryptedField;
+type DecryptionResult<T> = DecryptionSuccess<T> | DecryptionError<T>;
 /**
- * Build an encrypt config from a list of encrypted tables.
- *
- * @param protectTables - The list of encrypted tables to build the config from.
- * @returns An encrypt config object.
- *
- * @example
- * ```typescript
- * import { buildEncryptConfig } from "@cipherstash/stack/schema"
- *
- * const users = encryptedTable("users", {
- *   email: encryptedColumn("email").equality(),
- * })
- *
- * const orders = encryptedTable("orders", {
- *   amount: encryptedColumn("amount").dataType("number"),
- * })
+ * User-facing query type names for encrypting query values.
  *
- * const config = buildEncryptConfig(users, orders)
- * console.log(config)
- * ```
+ * - `'equality'`: Exact match. [Exact Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)
+ * - `'freeTextSearch'`: Text search. [Match Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)
+ * - `'orderAndRange'`: Comparison and range. [Range Queries](https://cipherstash.com/docs/stack/cipherstash/encryption/searchable-encryption)
+ * - `'steVecSelector'`: JSONPath selector (e.g. `'$.user.email'`)
+ * - `'steVecTerm'`: Containment (e.g. `{ role: 'admin' }`)
+ * - `'searchableJson'`: Auto-infers selector or term from plaintext type (recommended)
  */
-declare function buildEncryptConfig(...protectTables: Array<BuildableTable>): EncryptConfig;
+type QueryTypeName = 'orderAndRange' | 'freeTextSearch' | 'equality' | 'steVecSelector' | 'steVecTerm' | 'searchableJson';
+declare const queryTypes: {
+    readonly orderAndRange: "orderAndRange";
+    readonly freeTextSearch: "freeTextSearch";
+    readonly equality: "equality";
+    readonly steVecSelector: "steVecSelector";
+    readonly steVecTerm: "steVecTerm";
+    readonly searchableJson: "searchableJson";
+};
+/** @internal */
+type QueryTermBase = {
+    column: BuildableQueryColumn;
+    table: BuildableTable;
+    queryType?: QueryTypeName;
+    returnType?: EncryptedReturnType;
+};
+type EncryptQueryOptions = QueryTermBase;
+type ScalarQueryTerm = QueryTermBase & {
+    value: Plaintext;
+};
 
-export { type OtherFields as $, type SteVecIndexOpts as A, type BulkEncryptPayload as B, type ClientConfig as C, type Decrypted as D, type EncryptedReturnType as E, buildEncryptConfig as F, castAsEnum as G, encryptConfigSchema as H, type InferEncrypted as I, eqlCastAsEnum as J, type KeysetIdentifier as K, toEqlCastAs as L, type MatchIndexOpts as M, type BuildableTableColumns as N, type OreIndexOpts as O, type Plaintext as P, type QueryTypeName as Q, type BuildableV3QueryableColumn as R, type ScalarQueryTerm as S, type TokenFilter as T, type UniqueIndexOpts as U, type DecryptedFields as V, type DecryptionResult as W, type EncryptedFields as X, type EncryptedFromSchema as Y, type EncryptedQuery as Z, type EncryptedSearchTerm as _, type Encrypted as a, type SearchTerm as a0, queryTypes as a1, type EncryptOptions as b, type BulkDecryptPayload as c, encryptedField as d, encryptedColumn as e, encryptedTable as f, EncryptedTable as g, type EncryptedTableColumn as h, type ColumnSchema as i, type EncryptConfig as j, EncryptedColumn as k, type CastAs as l, type EncryptedValue as m, type EncryptedQueryResult as n, type Client as o, type BulkDecryptedData as p, type BulkEncryptedData as q, type BuildableColumn as r, type BuildableTable as s, type EncryptQueryOptions as t, type BuildableQueryColumn as u, type EncryptedFromBuildableTable as v, type EncryptionClientConfig as w, EncryptedField as x, type InferPlaintext as y, type EqlCastAs as z };
+export { encryptedTable as $, type EncryptedTableColumn as A, type BuildableColumn as B, type CastAs as C, type Decrypted as D, type EncryptConfig as E, type EncryptedValue as F, type EncryptionClientConfig as G, type EqlCastAs as H, type InferEncrypted as I, type InferPlaintext as J, type KeysetIdentifier as K, type OreIndexOpts as L, type MatchIndexOpts as M, type OtherFields as N, type OpeIndexOpts as O, type Plaintext as P, type QueryTypeName as Q, type SearchTerm as R, type ScalarQueryTerm as S, type SteVecIndexOpts as T, type TokenFilter as U, type UniqueIndexOpts as V, buildEncryptConfig as W, castAsEnum as X, encryptConfigSchema as Y, encryptedColumn as Z, encryptedField as _, type BuildableQueryColumn as a, eqlCastAsEnum as a0, queryTypes as a1, toEqlCastAs as a2, type BuildableTable as b, type BuildableTableColumns as c, type BuildableV3QueryableColumn as d, type BulkDecryptPayload as e, type BulkDecryptedData as f, type BulkEncryptPayload as g, type BulkEncryptedData as h, type Client as i, type ClientConfig as j, type ColumnSchema as k, type DecryptedFields as l, type DecryptionResult as m, type EncryptOptions as n, type EncryptQueryOptions as o, type Encrypted as p, EncryptedColumn as q, EncryptedField as r, type EncryptedFields as s, type EncryptedFromBuildableTable as t, type EncryptedFromSchema as u, type EncryptedQuery as v, type EncryptedQueryResult as w, type EncryptedReturnType as x, type EncryptedSearchTerm as y, EncryptedTable as z };