feat(stack): EQL v3 typed schema + strongly-typed client (@cipherstash/stack/schema/v3, /v3)

.changeset/eql-v3-ffi-0-28-concrete-types.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/stack': minor
+---
+
+Upgrade `@cipherstash/protect-ffi` to 0.28.0 and update EQL v3 concrete Postgres domain names to match the SQL fixture (`integer*`, `smallint*`, `bool`, `real*`, and `double*`). The public factories remain semantic (`Integer`, `Smallint`, `Boolean`, `Real`, `Double`) while their concrete domains change, so this is a minor release.

.changeset/eql-v3-public-domains.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/stack': patch
+---
+
+Re-vendor the EQL v3 SQL bundle and align the v3 DSL to it: encrypted type domains now live in the `public` schema (`public.text`, `public.integer`, …) rather than `eql_v3`, and the boolean domain is `public.boolean` (was `eql_v3.bool`). The `eql_v3` schema now holds only the operator-backing functions, and the index-term constructors (`hmac_256`, `ore_block_256`, `bloom_filter`) moved to `eql_v3_internal`. This keeps the SDK's emitted domain names byte-matched to the installed bundle so `CREATE TABLE`/cast resolution succeeds.

.changeset/eql-v3-text-search.md

@@ -0,0 +1,18 @@
+---
+"@cipherstash/stack": minor
+---
+
+Add the EQL v3 `text_search` authoring DSL on a new `@cipherstash/stack/eql/v3`
+subpath (`types.TextSearch`, v3 `encryptedTable` / `buildEncryptConfig`). The v3
+builders emit the existing `EncryptConfig` shape, so encryption, payloads, and
+query paths are unchanged at runtime.
+
+Also widens the public client types (`EncryptionClientConfig.schemas`,
+`EncryptOptions`, `SearchTerm`/`EncryptQueryOptions`) to a structural contract so
+both v2 and v3 builders are accepted by `Encryption` / `encrypt` / `decrypt` /
+`encryptQuery`. This is a backward-compatible widening — existing v2 usage is
+unaffected. The structural contracts themselves (`BuildableColumn`,
+`BuildableQueryColumn`, `BuildableV3QueryableColumn`, `BuildableTable`,
+`BuildableTableColumns`) and the `encryptModel` return-type mapper
+(`EncryptedFromBuildableTable`) are exported from `@cipherstash/stack/types` so
+consumers can name them.

.changeset/eql-v3-typed-client.md

@@ -0,0 +1,29 @@
+---
+"@cipherstash/stack": minor
+---
+
+Add a strongly-typed EQL v3 client surface on a new `@cipherstash/stack/v3`
+subpath (`EncryptionV3`, `typedClient`, `TypedEncryptionClient`). It re-exports
+the v3 `types` namespace and table API (from `@cipherstash/stack/eql/v3`), so a
+single import provides everything needed to author and use a v3 schema.
+
+Every method derives its types from the concrete `table` / `column` builder
+arguments:
+
+- `encrypt` / `encryptQuery` pin the plaintext to the column's domain type
+  (`text → string`, `timestamp → Date`, …).
+- `encryptQuery` constrains `queryType` to the column's capabilities and rejects
+  storage-only columns at compile time.
+- `encryptModel` / `bulkEncryptModels` validate schema-column fields against their
+  inferred plaintext type (passthrough fields are untouched) and return a precise
+  encrypted model.
+- `decryptModel` / `bulkDecryptModels` return the precise plaintext model,
+  reconstructing `Date` values from the encrypt-config `cast_as`.
+
+Because the typed methods bind to the concrete branded v3 classes, a hand-rolled
+structural table/column is rejected — closing the soundness gap where a non-branded
+table could be encrypted at runtime while typed as plaintext.
+
+Runtime behaviour is unchanged: the encrypt/query paths return the same operations
+as the base client; only the model-decrypt paths add a per-column `Date`
+reconstruction step. The v2 client surface (`Encryption`) is untouched.

.changeset/eql-v3-typed-schema.md

@@ -0,0 +1,7 @@
+---
+'@cipherstash/stack': minor
+---
+
+Add EQL v3 schema builders for supported generated SQL domains under `@cipherstash/stack/eql/v3`, exposed as the `types` namespace (one member per supported EQL v3 domain, e.g. `types.TextEq` / `types.IntegerOrd` / `types.Timestamp`), including explicit query capability metadata (`getQueryCapabilities()` / `isQueryable()`) and v3 table support in model encryption helpers (`encryptModel` / `bulkEncryptModels`).
+
+Also widen the accepted plaintext input type for `encrypt` / `encryptQuery` to include `Date` (via the new `Plaintext` type), so v3 `date` / `timestamp` domains can be encrypted and queried with their natural JavaScript values.

.changeset/skip-v3-bigint.md

@@ -0,0 +1,5 @@
+---
+'@cipherstash/stack': patch
+---
+
+Omit EQL v3 bigint factories from the public DSL and test matrix until native bigint round-tripping is supported.

.github/actions/require-cs-secrets/action.yml

@@ -0,0 +1,43 @@
+name: Require CipherStash secrets
+description: >-
+  Fail the job when any CS_* credential is missing. The live test suites gate
+  themselves on these vars (vitest `describe.skip`, Deno `test.ignore`), so a
+  rotated / cleared / fork-PR-absent secret would make them silently skip and
+  let CI go green with ZERO live coverage. This turns that silent skip into a
+  loud failure. Requires the repo to be checked out first (local action path).
+
+inputs:
+  workspace-crn:
+    description: secrets.CS_WORKSPACE_CRN
+    required: true
+  client-id:
+    description: secrets.CS_CLIENT_ID
+    required: true
+  client-key:
+    description: secrets.CS_CLIENT_KEY
+    required: true
+  client-access-key:
+    description: secrets.CS_CLIENT_ACCESS_KEY
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Assert CS_* secrets are present
+      shell: bash
+      env:
+        CS_WORKSPACE_CRN: ${{ inputs.workspace-crn }}
+        CS_CLIENT_ID: ${{ inputs.client-id }}
+        CS_CLIENT_KEY: ${{ inputs.client-key }}
+        CS_CLIENT_ACCESS_KEY: ${{ inputs.client-access-key }}
+      run: |
+        missing=0
+        for v in CS_WORKSPACE_CRN CS_CLIENT_ID CS_CLIENT_KEY CS_CLIENT_ACCESS_KEY; do
+          if [ -z "${!v}" ]; then
+            echo "::error::Required secret $v is not set on this runner — live test suites would silently skip."
+            missing=1
+          fi
+        done
+        if [ "$missing" -ne 0 ]; then
+          exit 1
+        fi

.github/workflows/fta-v3.yml

@@ -0,0 +1,65 @@
+name: "FTA Complexity (EQL v3)"
+
+# Blocking complexity gate for the EQL v3 text-search schema. Runs the Fast
+# TypeScript Analyzer (fta-cli) against the v3 source directory only and fails
+# the check when any file exceeds the score cap (`--score-cap` in the
+# `analyze:complexity` script). FTA is pure static source analysis, so this job
+# needs no build step, database, or credentials.
+
+on:
+  push:
+    branches:
+      - 'main'
+    paths:
+      - 'packages/stack/src/eql/v3/**'
+      # Shared match-index defaults live outside src/eql/v3 but shape every
+      # emitted v3 match block (load-bearing `k`/`m` ciphertext params), so edits
+      # here must trigger the v3 gate too.
+      - 'packages/stack/src/schema/match-defaults.ts'
+      - 'packages/stack/package.json'
+      - '.github/workflows/fta-v3.yml'
+  pull_request:
+    branches:
+      - "**"
+    paths:
+      - 'packages/stack/src/eql/v3/**'
+      - 'packages/stack/src/schema/match-defaults.ts'
+      - 'packages/stack/package.json'
+      - '.github/workflows/fta-v3.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  fta:
+    name: Analyze v3 complexity
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+
+      - uses: pnpm/action-setup@v6.0.8
+        name: Install pnpm
+        with:
+          run_install: false
+
+      - name: Install Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: 'pnpm'
+
+      # node-pty's install hook falls back to `node-gyp rebuild` when no
+      # linux-x64 prebuild matches. pnpm/action-setup v6 no longer ships
+      # node-gyp on PATH, so install it explicitly.
+      - name: Install node-gyp
+        run: npm install -g node-gyp
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      # Non-zero exit (score above the cap) fails the check — this is the
+      # blocking gate. No `continue-on-error`.
+      - name: Analyze v3 complexity
+        run: pnpm --filter @cipherstash/stack run analyze:complexity

.github/workflows/prisma-example-readme-e2e.yml

@@ -65,6 +65,16 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # A missing / rotated / fork-PR-absent secret makes the walkthrough skip
+      # its live steps silently, hiding regressions behind a green job. Fail loud.
+      - name: Require CipherStash secrets
+        uses: ./.github/actions/require-cs-secrets
+        with:
+          workspace-crn: ${{ secrets.CS_WORKSPACE_CRN }}
+          client-id: ${{ secrets.CS_CLIENT_ID }}
+          client-key: ${{ secrets.CS_CLIENT_KEY }}
+          client-access-key: ${{ secrets.CS_CLIENT_ACCESS_KEY }}
+
       # Build via turbo so `^build` on `@cipherstash/prisma-next` and
       # its `@cipherstash/stack` peer is honoured. The test's
       # `pnpm install` subprocess inside `examples/prisma/` is a no-op

.github/workflows/prisma-next-e2e.yml

@@ -67,6 +67,17 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # The global-setup hook hard-errors without CS_WORKSPACE_CRN, but a
+      # missing sibling secret could still degrade coverage silently — assert
+      # all four up front so a rotated / fork-PR-absent secret fails loudly.
+      - name: Require CipherStash secrets
+        uses: ./.github/actions/require-cs-secrets
+        with:
+          workspace-crn: ${{ secrets.CS_WORKSPACE_CRN }}
+          client-id: ${{ secrets.CS_CLIENT_ID }}
+          client-key: ${{ secrets.CS_CLIENT_KEY }}
+          client-access-key: ${{ secrets.CS_CLIENT_ACCESS_KEY }}
+
       # Write the CS_* credentials and the harness DATABASE_URL into the
       # example app's .env so the runtime + the `prisma-next migration
       # apply` invocation in global-setup both pick them up. The harness

.github/workflows/tests.yml

@@ -59,6 +59,19 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Fail loudly if any live-test credential is missing, so the v3 live
+      # matrix (and every other `describeLive` suite) can't silently skip.
+      - name: Require CipherStash secrets
+        uses: ./.github/actions/require-cs-secrets
+        with:
+          workspace-crn: ${{ secrets.CS_WORKSPACE_CRN }}
+          client-id: ${{ secrets.CS_CLIENT_ID }}
+          client-key: ${{ secrets.CS_CLIENT_KEY }}
+          client-access-key: ${{ secrets.CS_CLIENT_ACCESS_KEY }}
+
+      - name: Type tests (stack)
+        run: pnpm --filter @cipherstash/stack run test:types
+
       - name: Lint — no hardcoded package-manager runners
         run: pnpm run lint:runners
 
@@ -149,6 +162,16 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      # Auth-dependent `e2e/` suites skip themselves without these vars — a
+      # silent skip would hide regressions behind a green job. Fail loudly.
+      - name: Require CipherStash secrets
+        uses: ./.github/actions/require-cs-secrets
+        with:
+          workspace-crn: ${{ secrets.CS_WORKSPACE_CRN }}
+          client-id: ${{ secrets.CS_CLIENT_ID }}
+          client-key: ${{ secrets.CS_CLIENT_KEY }}
+          client-access-key: ${{ secrets.CS_CLIENT_ACCESS_KEY }}
+
       # Run the standalone `e2e/` workspace via turbo so the `^build`
       # dep on the `test:e2e` task builds cli + wizard first. CLI's own
       # E2E (`packages/cli/tests/e2e/**`) is covered by the `run-tests`
@@ -157,7 +180,7 @@ jobs:
         run: pnpm exec turbo run test:e2e --filter @cipherstash/e2e
 
   # Verifies @cipherstash/stack/wasm-inline works under Deno — i.e. the
-  # WASM build of protect-ffi 0.25+ and auth 0.38+ can round-trip an
+  # WASM build of protect-ffi 0.26+ and auth 0.40+ can round-trip an
   # encryption against ZeroKMS / CTS in a runtime with no native
   # bindings available. The deno.json deliberately omits --allow-ffi so
   # a silent fallback to the NAPI module is impossible.
@@ -216,19 +239,17 @@ jobs:
       - name: Build stack
         run: pnpm exec turbo run build --filter @cipherstash/stack
 
-      # roundtrip.test.ts skips itself (Deno.test.ignore) when any of
-      # the four CS_* env vars is missing — that's the right behaviour
-      # for local runs, but in CI a silent skip would mean a rotated /
-      # cleared secret hides a real WASM regression behind a green job.
-      # Fail loudly instead.
-      - name: Assert CS_* secrets are present
-        run: |
-          for v in CS_WORKSPACE_CRN CS_CLIENT_ID CS_CLIENT_KEY CS_CLIENT_ACCESS_KEY; do
-            if [ -z "${!v}" ]; then
-              echo "::error::Required secret $v is not set on this runner — the WASM smoke test would silently skip."
-              exit 1
-            fi
-          done
+      # roundtrip.test.ts skips itself (Deno.test.ignore) when any of the four
+      # CS_* env vars is missing — fine locally, but in CI a silent skip would
+      # let a rotated / cleared secret hide a real WASM regression behind a
+      # green job. Fail loudly instead.
+      - name: Require CipherStash secrets
+        uses: ./.github/actions/require-cs-secrets
+        with:
+          workspace-crn: ${{ secrets.CS_WORKSPACE_CRN }}
+          client-id: ${{ secrets.CS_CLIENT_ID }}
+          client-key: ${{ secrets.CS_CLIENT_KEY }}
+          client-access-key: ${{ secrets.CS_CLIENT_ACCESS_KEY }}
 
       - name: Run Deno WASM smoke test
         working-directory: e2e/wasm